Templates

Learn how to create, update and publish PDFMonkey Templates using our API.

The DocumentTemplate object

The DocumentTemplate object is how we call a template in PDFMonkey. Is it composed of:

• HTML + Liquid for the (dynamic) content part

• CSS for styling

• Test Data for testing purposes

• Settings for printing options and details

States

A template contains two sets of properties:

• Draft properties for content that's not published yet (ex. body_draft, settings_draft)

• Properties currently used when genrating a document (ex. body, settings)

Attributes

Template JSON

{
  "id": "8ac0d8f7-dbd3-46dd-b2d3-af036a2776d9",
  "app_id": "3161c5e5-9966-4630-9b07-63f718092784",
  "identifier": "My Awesome Template",
  "edition_mode": "code",
  "body": "<p>Hello {{name}}</p>",
  "body_draft": "<p>Hello, <strong>{{name}}!</strong></p>",
  "scss_style": "p { color: green; }",
  "scss_style_draft": "p { color: purple; }",
  "sample_data": "{ \"name\": \"Peter Parker\" }",
  "sample_data_draft": "{ \"name\": \"Spider-Man\" }",
  "settings": {
    "footer": {
      "center": null,
      "content": null,
      "left": null,
      "right": "page [page]/[topage]"
    },
    "header": {
      "center": null,
      "content": null,
      "left": null,
      "right": null,
    },
    "inject_javascript": false,
    "margin": {
      "bottom": 0,
      "left": 0,
      "right": 0,
      "top": 0
    },
    "orientation": "portrait",
    "paper_format": "a4",
    "paper_height": 297,
    "paper_width": 210,
    "use_emojis": false,
    "use_forms": false,
    "use_paged": false
  },
  "settings_draft": {
    "footer": {
      "center": null,
      "content": null,
      "left": null,
      "right": "page [page]/[topage]"
    },
    "header": {
      "center": null,
      "content": null,
      "left": null,
      "right": null,
    },
    "inject_javascript": false,
    "margin": {
      "bottom": 0,
      "left": 0,
      "right": 0,
      "top": 0
    },
    "orientation": "portrait",
    "paper_format": "a4",
    "paper_height": 297,
    "paper_width": 210,
    "use_emojis": false,
    "use_forms": false,
    "use_paged": false
  },
  "pdf_engine_id": "5c709522-90db-4aea-b49f-15aeaa7180c7",
  "pdf_engine_draft_id": "5c709522-90db-4aea-b49f-15aeaa7180c7",
  "template_folder_id": null,
  "ttl": 86400,
  "created_at": "2050-01-02T03:04:05.678+02:00",
  "updated_at": "2050-01-02T03:04:05.678+02:00",
  "auth_token": "ZCsspcSZieyfdCUHYjKW1B9D8mnrz2ck",
  "checksum": "kfYsx6xzMx3JkYxLd4LW6YeU5rkcuTxQ",
  "preview_url": "https://preview.pdfmonkey.io/pdf/..."
}

Attribute	Type	Description
id	UUID	Unique identifier.
app_id	UUID	Unique identifier of the Template's Workspace.
identifier	String	Human name.
edition_mode	String	Can be code or visual.
body	String	Published HTML + Liquid content currently used to generate documents
body_draft	String	Unpublished HTML + Liquid content, not yet used for generation
scss_style	String	Published CSS or SCSS styles to apply to the content. Does not apply to header/footer.
scss_style_draft	String	Unpublished CSS or SCSS style.
sample_data	String	Not used. This "published" version can be used to rollback changes applied to the draft version.
sample_data_draft	String	JSON Data used to test the Template. Not used for generation, only for preview.
settings	Object	Published printing settings. See "Settings" below.
settings_draft	Object	Unpublished printing settings. See "Settings" below.
pdf_engine_id	UUID	Unique identifier of the PDF Engine to use when generating documents. See "PDF Engines" below.
pdf_engine_draft_id	UUID	Unique identifier of the PDF Engine to preview the draft version of the template with. Can be useful to test a new engine in preview before switching the published version to it. See "PDF Engines" below.
template_folder_id	UUID	Unique identifier of a Folder to group the Template into.
ttl	Number	Document expiration delay. See "TTL" below.
created_at	Date	Time at which the template was created.
updated_at	Date	Time at which the template was last updated.
auth_token	String	Generated. Not used.
checksum	String	Internal. Used mainly for the preview.
preview_url	String	This URL can be used to preview the Template using draft properties. This is what you can use to preview a Template when using an external editor to write it.

Settings

The settings attribute (and its draft counterpart settings_draft) is an object that contains various configuration options for the Template. These settings control the layout, formatting, and behavior of the generated Document.

Attribute	Type	Description
footer	Object	Configures the footer of the Document.
footer.left footer.center footer.right	String	Content for the left, center or right parts of the footer. Magic tokens [page] and [topage] can be used. HTML + Liquid is not supported.
header	Object	Configures the header of the Document.
header.left header.center header.right	String	Content for the left, center or right parts of the header. Magic tokens [page] and [topage] can be used. HTML + Liquid is not supported.
inject_javascript	Boolean	When set to true, the Document’s payload (or Test Data) will be accessible in JavaScript using the $docPayload variable. Rendering the full payload can impact performance. Only use it when needed.
margin	Object	Sets the margins of the Document.
margin.bottom margin.left margin.right margin.top	Number	Sets the bottom, left, right or top margins of the Document. Expressed in millimeters. Default is 10 if set to null or not defined.
orientation	String	Sets the page orientation. Can be either portrait or landscape.
paper_format	String	Specifies the paper format. Can be one of: a0 a1 a2 a3 a4 a5 a6 letter custom
paper_height	Number	Sets the paper height in millimeters. For non-custom paper sizes, this value is derived from the paper_format attribute and will be ignored.
paper_width	Number	Sets the paper width in millimeters. For non-custom paper sizes, this value is derived from the paper_format attribute and will be ignored.
use_emojis	Boolean	When set to true, enables emoji support (using [Noto Color Emoji](https://fonts.google.com/noto/specimen/Noto+Color+Emoji)) in the generated PDF.
use_forms	Boolean	When set to true, enables interactive PDF forms (AcroForms). The system detects markers in the format [% data_form_field_... %] and automatically converts them into fillable form fields.
use_paged	Boolean	Specific to PDF Engine v3, when set to true, the engine will wait for Paged.js to rendering to complete before generating the PDF. Other engines will ignore this setting.

PDF Engines

We provide different PDF Engines to generate documents. Each version has its own capabilities and limitations. The most recent and powerful one is v4. We strongly recommend using it.

The list of available PDF Engines can be found using the dedicated endpoint:

Engines request

curl https://api.pdfmonkey.io/api/v1/engines -H "Authorization: Bearer <YOUR API KEY>"

This endpoint currently returns the following:

Engines response

{
  "pdf_engines": [
    {
      "id": "61749ef7-6aca-4edb-84ca-685adb638c34",
      "name": "v3",
      "deprecated_on": null
    },
    {
      "id": "1f8da2ab-29c4-455c-a5fb-8771e44148c3",
      "name": "v2",
      "deprecated_on": null
    },
    {
      "id": "5c709522-90db-4aea-b49f-15aeaa7180c7",
      "name": "v4",
      "deprecated_on": null
    }
  ],
  "meta": {
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 1
  }
}

API Requests

List templates

get

List all templates

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

q[workspaceId]stringRequired

The workspace to search within

q[folders]stringOptional

Comma separated list of folder IDs to search within, use "none" to search only in root folder

pageone ofOptional

Pagination parameters

integerOptional

The page number to return

or

sortstring · enumOptional

Attribute to sort by

Possible values:

Responses

200

Document templates found

application/json

get

/document_template_cards

HTTPcURLJavaScriptPython

GET /api/v1/document_template_cards?q[workspaceId]=text HTTP/1.1
Host: api.pdfmonkey.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

Document templates found

{
  "document_template_cards": [
    {
      "id": "text",
      "app_id": "text",
      "auth_token": "text",
      "edition_mode": "text",
      "identifier": "text",
      "is_draft": true,
      "pdf_engine_deprecated_on": "text",
      "pdf_engine_name": "text",
      "template_folder_id": "text",
      "template_folder_identifier": "text",
      "created_at": "text",
      "updated_at": "text"
    }
  ],
  "meta": {
    "current_page": 1,
    "next_page": 1,
    "prev_page": 1,
    "total_pages": 1
  }
}

Create a template

post

Create a template

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

application/json

idstringRequired

The ID of the document template

app_idstringRequired

The ID of the workspace

identifierstringRequired

The human name of the document template

edition_modestring · enumOptional

The edition mode of the document template

Default: codePossible values:

bodystringOptional

The published body of the document template. Used to generate documents.

body_draftstringOptional

The draft body of the document template. Used to preview changes.

scss_stylestringOptional

The published (S)CSS style of the document template. Used to generate documents.

scss_style_draftstringOptional

The draft (S)CSS style of the document template. Used to preview changes.

sample_datastringOptional

The sample data of the document template. Used only to allow reverting changes.

sample_data_draftstringOptional

The draft sample data of the document template. Used to preview changes.

pdf_engine_idstringOptional

The ID of the PDF engine used to generate documents

pdf_engine_draft_idstring · nullableRequired

The ID of the PDF engine used to preview changes, allowing to test a template against a new engine.

ttlinteger · enumOptional

The time-to-live of the document template. Used to automatically delete documents after a certain amount of time. Available options depend on you plan. In case the value is too high, the highest available value will be used instead.

300: 5 minutes 1200: 20 minutes 3600: 1 hour 86400: 1 day 604800: 1 week (Pro, Pro+, Premium) 2592000: 1 month (Pro+, Premium) 31536000: 1 year (Pro+, Premium) 0: None (Pro+, Premium)

Possible values:

created_atstringOptional

The date and time the document template was created

updated_atstringOptional

The date and time the document template was last updated

auth_tokenstringOptional

Internal

checksumstringOptional

Internal

preview_urlstringOptional

URL of the template preview. Can be used directly or in an iframe to preview the template.

Responses

201

Template created

application/json

post

/document_templates

HTTPcURLJavaScriptPython

POST /api/v1/document_templates HTTP/1.1
Host: api.pdfmonkey.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 762

{
  "id": "text",
  "app_id": "text",
  "identifier": "text",
  "edition_mode": "code",
  "body": "text",
  "body_draft": "text",
  "scss_style": "text",
  "scss_style_draft": "text",
  "sample_data": "text",
  "sample_data_draft": "text",
  "settings": {
    "footer": null,
    "header": null,
    "inject_javascript": false,
    "margin": null,
    "orientation": "text",
    "paper_format": "text",
    "paper_height": 297,
    "paper_width": 210,
    "use_emojis": false,
    "use_paged": false
  },
  "settings_draft": {
    "footer": null,
    "header": null,
    "inject_javascript": false,
    "margin": null,
    "orientation": "text",
    "paper_format": "text",
    "paper_height": 297,
    "paper_width": 210,
    "use_emojis": false,
    "use_paged": false
  },
  "pdf_engine_id": "text",
  "pdf_engine_draft_id": "text",
  "ttl": 300,
  "created_at": "text",
  "updated_at": "text",
  "auth_token": "text",
  "checksum": "text",
  "preview_url": "text"
}

201

Template created

{
  "document_template": {
    "id": "text",
    "app_id": "text",
    "identifier": "text",
    "edition_mode": "code",
    "body": "text",
    "body_draft": "text",
    "scss_style": "text",
    "scss_style_draft": "text",
    "sample_data": "text",
    "sample_data_draft": "text",
    "settings": {
      "footer": null,
      "header": null,
      "inject_javascript": false,
      "margin": null,
      "orientation": "text",
      "paper_format": "text",
      "paper_height": 297,
      "paper_width": 210,
      "use_emojis": false,
      "use_paged": false
    },
    "settings_draft": {
      "footer": null,
      "header": null,
      "inject_javascript": false,
      "margin": null,
      "orientation": "text",
      "paper_format": "text",
      "paper_height": 297,
      "paper_width": 210,
      "use_emojis": false,
      "use_paged": false
    },
    "pdf_engine_id": "text",
    "pdf_engine_draft_id": "text",
    "ttl": 300,
    "created_at": "text",
    "updated_at": "text",
    "auth_token": "text",
    "checksum": "text",
    "preview_url": "text"
  }
}

Get a template

get

Get a template

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

idstringRequired

The ID of the template

Responses

200

Template found

application/json

get

/document_templates/{id}

HTTPcURLJavaScriptPython

GET /api/v1/document_templates/{id} HTTP/1.1
Host: api.pdfmonkey.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

Template found

{
  "document_template": {
    "id": "text",
    "app_id": "text",
    "identifier": "text",
    "edition_mode": "code",
    "body": "text",
    "body_draft": "text",
    "scss_style": "text",
    "scss_style_draft": "text",
    "sample_data": "text",
    "sample_data_draft": "text",
    "settings": {
      "footer": null,
      "header": null,
      "inject_javascript": false,
      "margin": null,
      "orientation": "text",
      "paper_format": "text",
      "paper_height": 297,
      "paper_width": 210,
      "use_emojis": false,
      "use_paged": false
    },
    "settings_draft": {
      "footer": null,
      "header": null,
      "inject_javascript": false,
      "margin": null,
      "orientation": "text",
      "paper_format": "text",
      "paper_height": 297,
      "paper_width": 210,
      "use_emojis": false,
      "use_paged": false
    },
    "pdf_engine_id": "text",
    "pdf_engine_draft_id": "text",
    "ttl": 300,
    "created_at": "text",
    "updated_at": "text",
    "auth_token": "text",
    "checksum": "text",
    "preview_url": "text"
  }
}

Update a template

put

Update a template

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

idstringRequired

The ID of the template

Body

application/json

idstringRequired

The ID of the document template

app_idstringRequired

The ID of the workspace

identifierstringRequired

The human name of the document template

edition_modestring · enumOptional

The edition mode of the document template

Default: codePossible values:

bodystringOptional

The published body of the document template. Used to generate documents.

body_draftstringOptional

The draft body of the document template. Used to preview changes.

scss_stylestringOptional

The published (S)CSS style of the document template. Used to generate documents.

scss_style_draftstringOptional

The draft (S)CSS style of the document template. Used to preview changes.

sample_datastringOptional

The sample data of the document template. Used only to allow reverting changes.

sample_data_draftstringOptional

The draft sample data of the document template. Used to preview changes.

pdf_engine_idstringOptional

The ID of the PDF engine used to generate documents

pdf_engine_draft_idstring · nullableRequired

The ID of the PDF engine used to preview changes, allowing to test a template against a new engine.

ttlinteger · enumOptional

The time-to-live of the document template. Used to automatically delete documents after a certain amount of time. Available options depend on you plan. In case the value is too high, the highest available value will be used instead.

300: 5 minutes 1200: 20 minutes 3600: 1 hour 86400: 1 day 604800: 1 week (Pro, Pro+, Premium) 2592000: 1 month (Pro+, Premium) 31536000: 1 year (Pro+, Premium) 0: None (Pro+, Premium)

Possible values:

created_atstringOptional

The date and time the document template was created

updated_atstringOptional

The date and time the document template was last updated

auth_tokenstringOptional

Internal

checksumstringOptional

Internal

preview_urlstringOptional

URL of the template preview. Can be used directly or in an iframe to preview the template.

Responses

200

Template updated

application/json

put

/document_templates/{id}

HTTPcURLJavaScriptPython

PUT /api/v1/document_templates/{id} HTTP/1.1
Host: api.pdfmonkey.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 762

{
  "id": "text",
  "app_id": "text",
  "identifier": "text",
  "edition_mode": "code",
  "body": "text",
  "body_draft": "text",
  "scss_style": "text",
  "scss_style_draft": "text",
  "sample_data": "text",
  "sample_data_draft": "text",
  "settings": {
    "footer": null,
    "header": null,
    "inject_javascript": false,
    "margin": null,
    "orientation": "text",
    "paper_format": "text",
    "paper_height": 297,
    "paper_width": 210,
    "use_emojis": false,
    "use_paged": false
  },
  "settings_draft": {
    "footer": null,
    "header": null,
    "inject_javascript": false,
    "margin": null,
    "orientation": "text",
    "paper_format": "text",
    "paper_height": 297,
    "paper_width": 210,
    "use_emojis": false,
    "use_paged": false
  },
  "pdf_engine_id": "text",
  "pdf_engine_draft_id": "text",
  "ttl": 300,
  "created_at": "text",
  "updated_at": "text",
  "auth_token": "text",
  "checksum": "text",
  "preview_url": "text"
}

200

Template updated

{
  "document_template": {
    "id": "text",
    "app_id": "text",
    "identifier": "text",
    "edition_mode": "code",
    "body": "text",
    "body_draft": "text",
    "scss_style": "text",
    "scss_style_draft": "text",
    "sample_data": "text",
    "sample_data_draft": "text",
    "settings": {
      "footer": null,
      "header": null,
      "inject_javascript": false,
      "margin": null,
      "orientation": "text",
      "paper_format": "text",
      "paper_height": 297,
      "paper_width": 210,
      "use_emojis": false,
      "use_paged": false
    },
    "settings_draft": {
      "footer": null,
      "header": null,
      "inject_javascript": false,
      "margin": null,
      "orientation": "text",
      "paper_format": "text",
      "paper_height": 297,
      "paper_width": 210,
      "use_emojis": false,
      "use_paged": false
    },
    "pdf_engine_id": "text",
    "pdf_engine_draft_id": "text",
    "ttl": 300,
    "created_at": "text",
    "updated_at": "text",
    "auth_token": "text",
    "checksum": "text",
    "preview_url": "text"
  }
}

Delete a template

delete

Delete a template

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

idstringRequired

The ID of the template

Responses

204

Template deleted

delete

/document_templates/{id}

HTTPcURLJavaScriptPython

DELETE /api/v1/document_templates/{id} HTTP/1.1
Host: api.pdfmonkey.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

204

Template deleted

No content