HomePricingSign inRegister

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

List templates

get

List all templates

Authorizations
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
GET /api/v1/document_template_cards 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
Body
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
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
Path parameters
idstringRequired

The ID of the template

Responses
200
Template found
application/json
get
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
Path parameters
idstringRequired

The ID of the template

Body
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
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
Path parameters
idstringRequired

The ID of the template

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

Template deleted

No content
PreviousDocuments

Last updated

Was this helpful?