TL;DR
Sample HTTP request to generate a Document
Copy curl \
"https://api.pdfmonkey.io/api/v1/documents" \
-X POST \
-H 'Authorization: Bearer YOUR-API-KEY' \
-H 'Content-Type: application/json' \
-d '{
"document": {
"document_template_id": "ID-OF-YOUR-TEMPLATE",
"status": "pending", // To force generation to be queued upon creation
"payload": {
"clientName": "Peter Parker",
"orderDate": "2050-03-14",
"products": [
{ "name": "Spider silk", "quantity": 12, "unitPrice": 123.50 },
{ "name": "Spandex fabric", "quantity": 2, "unitPrice": 28.90 }
]
},
"meta": {
"_filename": "2050-03-14 Peter Parker.pdf",
"clientRef": "spidey-616"
}
}
}'
Response
Copy {
"document" : {
"id" : "12345678-1234-1234-1234-123456789012" ,
"document_template_id" : "ID-OF-YOUR-TEMPLATE" ,
"status" : "generating" , // Document is queued (could also still be "pending")
"failure_cause" : null , // Filled in case of error
"filename" : "2050-03-14 Peter Parker.pdf" ,
"download_url" : null , // Not filled until generation success
"preview_url" : "https://..." , // Usable to embed a preview of the PDF in your app
"public_share_link" : null , // Filled upon generation success on a Pro+/Premium plan
"payload" : {
"clientName" : "Peter Parker" ,
"orderDate" : "2050-03-14" ,
"products" : [
{ "name" : "Spider silk" , "quantity" : 12 , "unitPrice" : 123.50 } ,
{ "name" : "Spandex fabric" , "quantity" : 2 , "unitPrice" : 28.90 }
]
} ,
"meta" : {
"_filename" : "2050-03-14 Peter Parker.pdf" ,
"clientRef" : "spidey-616"
} ,
"created_at" : "2050-03-13T12:34:56.181+02:00" ,
"updated_at" : "2050-03-13T12:34:56.181+02:00"
}
}
Sample HTTP request to fetch details about a document
Copy curl \
-H 'Authorization: Bearer YOUR-API-KEY' \
https://api.pdfmonkey.io/api/v1/document_cards/12345678-1234-1234-1234-123456789012
Response
Copy {
"id" : "12345678-1234-1234-1234-123456789012" ,
"app_id" : "c2b67b84-4aac-49ea-bed8-69a15d7a65d3" ,
"created_at" : "2022-04-07T11:01:38.201+02:00" ,
"document_template_id" : "96611e9e-ab03-4ac3-8551-1b485210c892" ,
"document_template_identifier" : "My Awesome Template" ,
"download_url": "https://pdfmonkey.s3.eu-west-1.amazonaws.com/production/backend/document/11475e57-0334-4ad5-8896-9462a2243957/my-test-document.pdf?response-content-disposition=attachment&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAJ2ZTKW4HMOLK63IQ%2F20220406%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Date=20220407T204150Z&X-Amz-Expires=900&X-Amz-SignedHeaders=host&X-Amz-Signature=24e3a8c0801ad8d1efd6aaa22d946ee70f5c8d5b55c586f346a094afa5046c77",
"failure_cause" : null ,
"filename" : "my-test-document.pdf" ,
"meta" : "{ \"_filename\":\"my-test-document.pdf\" }" ,
"public_share_link" : "https://files.pdfmonkey.io/share/72BE2293-D130-4C19-9E11-C82B5CEA8C37/my-test-document.pdf" ,
"status" : "success" ,
"updated_at" : "2022-04-07T11:01:41.181+02:00"
}
Two Objects To Know
When you interact with your Documents, there are two objects you need to be aware of: Document
and DocumentCard
.
The main distinction between the two is that DocumentCard
does not include the payload
attribute of the Document. This matters because in many cases, this attribute will have a important size and will thus have an impact on performance on both your side and ours.
Rules of thumb
Always prefer DocumentCard
unless you really need access to payload
Store any data you need later on in meta
instead of (or in addition to) payload
that way you won't need access to payload
The Document object
The Document object represents a single document (PDF), with its status, data and meta-data. It is used to manipulate the data used to generate a PDF.
Attributes
Copy {
"id" : "11475e57-0334-4ad5-8896-9462a2243957" ,
"app_id" : "c2b67b84-4aac-49ea-bed8-69a15d7a65d3" ,
"checksum" : "c230530f6f0aa32900af0924cf228e5c" ,
"created_at" : "2022-04-07T11:01:38.201+02:00" ,
"document_template_id" : "96611e9e-ab03-4ac3-8551-1b485210c892" ,
"download_url": "https://pdfmonkey.s3.eu-west-1.amazonaws.com/production/backend/document/11475e57-0334-4ad5-8896-9462a2243957/my-test-document.pdf?response-content-disposition=attachment&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAJ2ZTKW4HMOLK63IQ%2F20220406%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Date=20220407T204150Z&X-Amz-Expires=900&X-Amz-SignedHeaders=host&X-Amz-Signature=24e3a8c0801ad8d1efd6aaa22d946ee70f5c8d5b55c586f346a094afa5046c77",
"failure_cause" : null ,
"filename" : "my-test-document.pdf" ,
"generation_logs" : [
{
"type" : "info" ,
"message" : "Starting PDF generation." ,
"timestamp" : "Thu, 07 Apr 2022 09:01:39 GMT"
} ,
{
"type" : "info" ,
"message": "CONTEXT: {\n origin: 'backend',\n type: 'document',\n id: '11475e57-0334-4ad5-8896-9462a2243957',\n filename: 'my-test-document.pdf'\n}",
"timestamp" : "Thu, 07 Apr 2022 09:01:39 GMT"
} ,
{
"type" : "info" ,
"message" : "Generation took 1617ms to load and render." ,
"timestamp" : "Thu, 07 Apr 2022 09:01:40 GMT"
} ,
{
"type" : "info" ,
"message" : "Content size is 96302." ,
"timestamp" : "Thu, 07 Apr 2022 09:01:40 GMT"
} ,
{
"type" : "info" ,
"message": "Document stored as production/backend/document/11475e57-0334-4ad5-8896-9462a2243957/my-test-document.pdf",
"timestamp" : "Thu, 07 Apr 2022 09:01:40 GMT"
}
] ,
"meta" : "{ \"_filename\":\"my-test-document.pdf\" }" ,
"payload" : "{ \"name\": \"Peter Parker\" }" ,
"preview_url": "https://preview.pdfmonkey.io/pdf/web/viewer.html?file=https%3A%2F%2Fpreview.pdfmonkey.io%2Fdocument-render%2F11475e57-0334-4ad5-8896-9462a2243957%2Fc230530f6f0aa32900af0924cf228e5c",
"public_share_link" : "https://files.pdfmonkey.io/share/72BE2293-D130-4C19-9E11-C82B5CEA8C37/my-test-document.pdf" ,
"status" : "success" ,
"updated_at" : "2022-04-07T11:01:41.181+02:00"
}
id
(String, UUID) Unique identifier for the object.
app_id
(String, UUID) Unique identifier of the Document's Workspace.
checksum
(String) Internal checksum of the Document's content, mainly used for the Document's preview.
created_at
(String, Date) Time at which the object was created.
document_template_id
(String, UUID) Unique identifier of the Document's Template.
download_url
(String, URL) The URL at which the Document can be downloaded.
Valid for 1 hour
Any time you fetch the details of a document, you get a fresh download URL. It is valid for 1 hour. Once that time has passed, you'll need to fetch the Document's details again to get a fresh URL.
failure_cause
(String) In case the Document's status is failure
, this field will contain the reason of the failure. In any other case, this will be null
.
filename
(String) Name of the generated file when the Document's status is success
, will be null
otherwise.
generation_logs
(Array of Objects) Logs collected during the Document's generation. Can be especially useful in case of generation failure.
type: Can be info
or error
message: The log message
timestamp: The date and time of the log message
Will default to an empty array []
before the generation.
meta
(String, JSON) The meta-data of the Document. Can be null
or an arbitrary object containing data that you want to attach to a Document. This can be useful when using integrations, like Zapier or Integromat, as the payload will not be accessible.
payload
(String, JSON) The dynamic data used to build the content of the Document. Must represent a JSON object, not an array.
preview_url
(String, URL) This URL is especially useful if you want to embed a preview of the PDF in your own UI. A good example of this is the preview in our own dashboard, when you create a new Document.
This is not a Download URL!
This attributes is often mixed up with the Download URL but it cannot be used to download a generated PDF, it should only be used in an iframe
.
public_share_link
(String, URL) This URL will be present if your account has Share Links enabled. It is a permalink to the generated PDF.
Premium plan only
The share links feature is only available for Premium plans.
status
(String) Represents the current status of the Documents. You can learn more in the Document Lifecycle documentation page .
updated_at
(String, Date) Time at which the object was last updated.
The DocumentCard object
The DocumentCard object is a lightweight version of the Document. It contains almost the same information but excludes the payload .
Attributes
Copy {
"id" : "11475e57-0334-4ad5-8896-9462a2243957" ,
"app_id" : "c2b67b84-4aac-49ea-bed8-69a15d7a65d3" ,
"created_at" : "2022-04-07T11:01:38.201+02:00" ,
"document_template_id" : "96611e9e-ab03-4ac3-8551-1b485210c892" ,
"document_template_identifier" : "My Awesome Template" ,
"download_url": "https://pdfmonkey.s3.eu-west-1.amazonaws.com/production/backend/document/11475e57-0334-4ad5-8896-9462a2243957/my-test-document.pdf?response-content-disposition=attachment&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAJ2ZTKW4HMOLK63IQ%2F20220406%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Date=20220407T204150Z&X-Amz-Expires=900&X-Amz-SignedHeaders=host&X-Amz-Signature=24e3a8c0801ad8d1efd6aaa22d946ee70f5c8d5b55c586f346a094afa5046c77",
"failure_cause" : null ,
"filename" : "my-test-document.pdf" ,
"meta" : "{ \"_filename\":\"my-test-document.pdf\" }" ,
"public_share_link" : "https://files.pdfmonkey.io/share/72BE2293-D130-4C19-9E11-C82B5CEA8C37/my-test-document.pdf" ,
"status" : "success" ,
"updated_at" : "2022-04-07T11:01:41.181+02:00"
}
id
(String, UUID) Unique identifier for the object.
app_id
(String, UUID) Unique identifier of the Document's Workspace.
created_at
(String, Date) Time at which the object was created.
document_template_id
(String, UUID) Unique identifier of the Document's Template.
document_template_identifier
(String) The name you gave to the Document's Template.
download_url
(String, URL) The URL at which the Document can be downloaded.
Valid for 1 hour
Any time you fetch the details of a document, you get a fresh download URL. It is valid for 1 hour. Once that time has passed, you'll need to fetch the Document's details again to get a fresh URL.
failure_cause
(String) In case the Document's status is failure
, this field will contain the reason of the failure. In any other case, this will be null
.
filename
(String) Name of the generated file when the Document's status is success
, will be null
otherwise.
meta
(String, JSON) The meta-data of the Document. Can be null
or an arbitrary object containing data that you want to attach to a Document. This can be useful when using integrations, like Zapier or Integromat, as the payload will not be accessible.
public_share_link
(String, URL) This URL will be present if your account has Share Links enabled. It is a permalink to the generated PDF.
Premium plan only
The share links feature is only available for Premium plans.
status
(String) Represents the current status of the Documents. You can learn more in the Document Lifecycle documentation page .
updated_at
(String, Date) Time at which the object was last updated.
Listing Documents
In most cases, when listing Documents, you will only need to use DocumentCards
.
Lists the DocumentCards for your Documents
GET
This endpoint is limited to 24 items and provides pagination data.
Query Parameters
Name Type Description Number of the page to show (default 1
)
List of Template IDs to filter on
Can be one of:
• success
• failure
• draft
ID of a workspace to filter on
Filter documents that have been updated after a given point in time (example 1640995200
for 2022-01-01 00:00:00
)
200: OK Listing DocumentCards
Copy {
"document_cards" : [
{
"id" : "11475e57-0334-4ad5-8896-9462a2243957" ,
"app_id" : "c2b67b84-4aac-49ea-bed8-69a15d7a65d3" ,
"created_at" : "2022-04-07T11:01:38.201+02:00" ,
"document_template_id" : "96611e9e-ab03-4ac3-8551-1b485210c892" ,
"document_template_identifier" : "My Awesome Template" ,
"download_url": "https://pdfmonkey.s3.eu-west-1.amazonaws.com/production/backend/document/11475e57-0334-4ad5-8896-9462a2243957/my-test-document.pdf?response-content-disposition=attachment&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAJ2ZTKW4HMOLK63IQ%2F20220406%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Date=20220407T204150Z&X-Amz-Expires=900&X-Amz-SignedHeaders=host&X-Amz-Signature=24e3a8c0801ad8d1efd6aaa22d946ee70f5c8d5b55c586f346a094afa5046c77",
"failure_cause" : null ,
"filename" : "my-test-document.pdf" ,
"meta" : "{ \"_filename\":\"my-test-document.pdf\" }" ,
"public_share_link": "https://files.pdfmonkey.io/share/5CEA8C37-D130-4C19-9E11-72BE2293C82B/my-test-document.pdf",
"status" : "success" ,
"updated_at" : "2022-04-03T11:12:56.023+02:00"
} ,
{
"id" : "a2243957-0334-4ad5-8896-11475e579462" ,
"app_id" : "c2b67b84-4aac-49ea-bed8-69a15d7a65d3" ,
"created_at" : "2022-04-07T11:01:38.201+02:00" ,
"document_template_id" : "96611e9e-ab03-4ac3-8551-1b485210c892" ,
"document_template_identifier" : "My Awesome Template" ,
"download_url": "https://pdfmonkey.s3.eu-west-1.amazonaws.com/production/backend/document/11475e57-0334-4ad5-8896-9462a2243957/my-test-document.pdf?response-content-disposition=attachment&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAJ2ZTKW4HMOLK63IQ%2F20220406%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Date=20220407T204150Z&X-Amz-Expires=900&X-Amz-SignedHeaders=host&X-Amz-Signature=24e3a8c0801ad8d1efd6aaa22d946ee70f5c8d5b55c586f346a094afa5046c77",
"failure_cause" : null ,
"filename" : "my-test-document.pdf" ,
"meta" : "{ \"_filename\":\"my-test-document.pdf\" }" ,
"public_share_link": "https://files.pdfmonkey.io/share/72BE2293-D130-4C19-9E11-C82B5CEA8C37/my-test-document.pdf",
"status" : "success" ,
"updated_at" : "2022-04-07T11:01:41.181+02:00"
}
]
}
Fetching a Document
Fetching a DocumentCard
Fetches the DocumentCard data for a given Document
GET
https://api.pdfmonkey.io/api/v1/document_cards/ID
Path Parameters
Name Type Description ID of the Document to fetch
200: OK Document was found
Copy {
"document_card" : {
"id" : "11475e57-0334-4ad5-8896-9462a2243957" ,
"app_id" : "c2b67b84-4aac-49ea-bed8-69a15d7a65d3" ,
"created_at" : "2022-04-07T11:01:38.201+02:00" ,
"document_template_id" : "96611e9e-ab03-4ac3-8551-1b485210c892" ,
"document_template_identifier" : "My Awesome Template" ,
"download_url": "https://pdfmonkey.s3.eu-west-1.amazonaws.com/production/backend/document/11475e57-0334-4ad5-8896-9462a2243957/my-test-document.pdf?response-content-disposition=attachment&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAJ2ZTKW4HMOLK63IQ%2F20220406%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Date=20220407T204150Z&X-Amz-Expires=900&X-Amz-SignedHeaders=host&X-Amz-Signature=24e3a8c0801ad8d1efd6aaa22d946ee70f5c8d5b55c586f346a094afa5046c77",
"failure_cause" : null ,
"filename" : "my-test-document.pdf" ,
"meta" : "{ \"_filename\":\"my-test-document.pdf\" }" ,
"public_share_link" : "https://files.pdfmonkey.io/share/72BE2293-D130-4C19-9E11-C82B5CEA8C37/my-test-document.pdf" ,
"status" : "success" ,
"updated_at" : "2022-04-07T11:01:41.181+02:00"
}
}
Fetching a Document
Fetches the data for a given Document
GET
https://api.pdfmonkey.io/api/v1/documents/ID
Path Parameters
Name Type Description ID of the Document to fetch
200: OK Document was found
Copy {
"document" : {
"id" : "11475e57-0334-4ad5-8896-9462a2243957" ,
"app_id" : "c2b67b84-4aac-49ea-bed8-69a15d7a65d3" ,
"checksum" : "c230530f6f0aa32900af0924cf228e5c" ,
"created_at" : "2022-04-07T11:01:38.201+02:00" ,
"document_template_id" : "96611e9e-ab03-4ac3-8551-1b485210c892" ,
"download_url": "https://pdfmonkey.s3.eu-west-1.amazonaws.com/production/backend/document/11475e57-0334-4ad5-8896-9462a2243957/my-test-document.pdf?response-content-disposition=attachment&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAJ2ZTKW4HMOLK63IQ%2F20220406%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Date=20220407T204150Z&X-Amz-Expires=900&X-Amz-SignedHeaders=host&X-Amz-Signature=24e3a8c0801ad8d1efd6aaa22d946ee70f5c8d5b55c586f346a094afa5046c77",
"failure_cause" : null ,
"filename" : "my-test-document.pdf" ,
"generation_logs" : [
{
"type" : "info" ,
"message" : "Starting PDF generation." ,
"timestamp" : "Thu, 07 Apr 2022 09:01:39 GMT"
} ,
{
"type" : "info" ,
"message": "CONTEXT: {\n origin: 'backend',\n type: 'document',\n id: '11475e57-0334-4ad5-8896-9462a2243957',\n filename: 'my-test-document.pdf'\n}",
"timestamp" : "Thu, 07 Apr 2022 09:01:39 GMT"
} ,
{
"type" : "info" ,
"message" : "Generation took 1617ms to load and render." ,
"timestamp" : "Thu, 07 Apr 2022 09:01:40 GMT"
} ,
{
"type" : "info" ,
"message" : "Content size is 96302." ,
"timestamp" : "Thu, 07 Apr 2022 09:01:40 GMT"
} ,
{
"type" : "info" ,
"message": "Document stored as production/backend/document/11475e57-0334-4ad5-8896-9462a2243957/my-test-document.pdf",
"timestamp" : "Thu, 07 Apr 2022 09:01:40 GMT"
}
] ,
"meta" : "{ \"_filename\":\"my-test-document.pdf\" }" ,
"payload" : "{ \"name\": \"Peter Parker\" }" ,
"preview_url": "https://preview.pdfmonkey.io/pdf/web/viewer.html?file=https%3A%2F%2Fpreview.pdfmonkey.io%2Fdocument-render%2F11475e57-0334-4ad5-8896-9462a2243957%2Fc230530f6f0aa32900af0924cf228e5c",
"public_share_link" : "https://files.pdfmonkey.io/share/72BE2293-D130-4C19-9E11-C82B5CEA8C37/my-test-document.pdf" ,
"status" : "success" ,
"updated_at" : "2022-04-07T11:01:41.181+02:00"
}
}
Creating a Document
Creates a Document
POST
https://api.pdfmonkey.io/api/v1/documents
Request Body
Name Type Description document[document_template_id]*
ID of the source Template to use
Data to use for the Document generation. Can be either an Object or a string of JSON. Must be a single Object in any case.
Meta-Data to attach to the Document. Can be either an Object or a string of JSON. Must be a single Object in any case.
Can be one of:
• draft
(default)
• pending
(to trigger generation)
201: Created Document Created 422: Unprocessable Entity Validation Error
Copy {
"document" : {
"id" : "11475e57-0334-4ad5-8896-9462a2243957" ,
"created_at" : "2022-05-09T16:53:14.487+02:00" ,
"document_template_id" : "96611e9e-ab03-4ac3-8551-1b485210c892" ,
"meta" : null ,
"payload" : null ,
"status" : "draft" ,
"updated_at" : "2022-05-09T16:53:14.487+02:00" ,
"app_id" : "c2b67b84-4aac-49ea-bed8-69a15d7a65d3" ,
"download_url" : null ,
"checksum" : "529e58bf3c29f864dc5d319318e7e30d" ,
"failure_cause" : null ,
"filename" : null ,
"generation_logs" : [] ,
"preview_url": "https://preview.pdfmonkey.io/pdf/web/viewer.html?file=https%3A%2F%2Fpreview.pdfmonkey.io%2Fdocument-render%2F8939a8b6-d4bb-49d5-816f-8909b04ae059%2F529e58bf3c29f864dc5d319318e7e30d",
"public_share_link" : null
}
}
Copy {
"errors" : {
"document_template_id" : [ "can't be blank" ]
}
}
Example
Copy POST https://api.pdfmonkey.io/api/v1/documents
Authorization : Bearer YOUR_API_KEY
Content-Type : application/json
{
"document" : {
"document_template_id" : "12345678-90ab-cdef-1234-567890abcdef" ,
"payload" : {
"name" : "Jane Doe"
} ,
"meta" : {
"clientId" : "ABC1234-DE" ,
"_filename" : "my-document.pdf"
}
}
}
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 the document[meta]
attribute. It can contain special keys to influence the generated filename for instance.
Generating the Document upon creation
If you want to generate the Document in one go, you can set its status to pending
. Doing so, the Document will be queued for generation directly.
Copy POST https://api.pdfmonkey.io/api/v1/documents
Authorization : Bearer YOUR_API_KEY
Content-Type : application/json
{
"document" : {
"document_template_id" : "12345678-90ab-cdef-1234-567890abcdef" ,
"status" : "pending" ,
"payload" : {
"name" : "Jane Doe"
} ,
"meta" : {
"clientId" : "ABC1234-DE" ,
"_filename" : "my-document.pdf"
}
}
}
Generating a Document
To generate a Document you can either:
Updating a Document
Updates an existing Document
PUT
https://api.pdfmonkey.io/api/v1/documents/ID
Request Body
Name Type Description document[document_template_id]
ID of the source Template to use
Data to use for the Document generation. Can be either an Object or a string of JSON. Must be a single Object in any case.
Meta-Data to attach to the Document. Can be either an Object or a string of JSON. Must be a single Object in any case.
Can be one of:
• draft
(default)
• pending
(to trigger generation)
200: OK Document Updated
Copy {
"document" : {
"id" : "8939a8b6-d4bb-49d5-816f-8909b04ae059" ,
"created_at" : "2022-05-09T16:53:14.487+02:00" ,
"document_template_id" : "4E666986-54C1-4CD8-BBE8-A3896CEEE6C7" ,
"meta" : null ,
"payload" : null ,
"status" : "draft" ,
"updated_at" : "2022-05-09T16:58:43.425+02:00" ,
"app_id" : "3161c5e5-9966-4630-9b07-63f718092738" ,
"download_url" : null ,
"checksum" : "529e58bf3c29f864dc5d319318e7e30d" ,
"failure_cause" : null ,
"filename" : null ,
"generation_logs" : [] ,
"preview_url": "https://preview.pdfmonkey.io/pdf/web/viewer.html?file=https%3A%2F%2Fpreview.pdfmonkey.io%2Fdocument-render%2F8939a8b6-d4bb-49d5-816f-8909b04ae059%2F529e58bf3c29f864dc5d319318e7e30d",
"public_share_link" : null
}
}
Deleting a Document
Deletes a Document
DELETE
https://api.pdfmonkey.io/api/v1/documents/ID
Path Parameters
Name Type Description ID of the Document to delete
204: No Content Document deleted