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_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_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_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

Last updated

Was this helpful?