Skip to main content

TemplateCreate

html is required for pdf and image templates. Fields not named here are ignored.

namestringrequired

Possible values: non-empty and <= 200 characters

slugstringrequired

Lowercase letters, digits and dashes, 1 to 64 of them, starting and ending with a letter or digit. New in the workspace.

Possible values: non-empty and <= 64 characters, Value must match regular expression ^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$

Example: invoice-de
descriptionstringnullable

Up to 2,000 characters.

Possible values: <= 2000 characters

kindTemplateKindrequired

pdf and image templates are HTML; docx and pptx templates are Word and PowerPoint files with tags in their text, rendered live from the Starter plan on (test renders on Free produce the marked PDF only).

Possible values: [pdf, image, docx, pptx]

engineEnginerequired

The template language: Jinja2 (Nunjucks), Liquid or Handlebars.

Possible values: [jinja2, liquid, handlebars]

htmlstring

The body markup in the template language, up to 2 MB.

Possible values: <= 2097152 characters

cssstring

The stylesheet, up to 1 MB.

Possible values: <= 1048576 characters

headstring

Extra markup for <head>, such as font links; up to 256 kB.

Possible values: <= 262144 characters

settings object

Rendering settings. A request's settings are deep-merged over the template's, which are merged over the defaults: only the keys you send change, and a section set to null (such as footer: null) is removed. The settings reference explains each key with examples.

paper object

PDF page size. Defaults to A4 portrait.

formatstring

A0 to A6, Letter, Legal, Tabloid or Ledger; A4 by default. Ignored when width and height are set.

Example: A4
widthstringnullable

Custom page width as a CSS length; needs height too.

Example: 100mm
heightstringnullable

Custom page height as a CSS length; needs width too.

Example: 150mm
landscapeboolean
Default value: false
margin object

Page margins as CSS lengths; 20mm top and bottom and 15mm left and right by default. Header and footer are drawn inside the top and bottom margin.

topstring
Example: 20mm
rightstring
Example: 15mm
bottomstring
Example: 20mm
leftstring
Example: 15mm
header objectnullable

Printed across the whole page width inside the top margin; null removes the template's.

htmlstring

Markup of the running header, rendered with the template's language and data. Elements with the classes pageNumber and totalPages show the page numbers.

heightstring

Height of the header box as a CSS length.

paddingstring

CSS padding inside the header box; 0 for designs that run edge to edge.

Default value: 0 10mm
footer objectnullable

Printed across the whole page width inside the bottom margin; null removes the template's.

htmlstring

Markup of the running footer, rendered like the header.

heightstring

Height of the footer box as a CSS length.

paddingstring

CSS padding inside the footer box; 0 for designs that run edge to edge.

Default value: 0 10mm
printBackgroundboolean

Print background colours and images.

Default value: true
scalenumber

Scales the page content, from 0.1 to 2.

Default value: 1
preferCssPageSizeboolean

Let @page rules in the CSS decide the page size instead of paper.

Default value: false
pageRangesstring

Keep only these pages of a PDF; empty keeps all. The page count, the plan's page limit and the units count the pages that are kept.

Default value:
Example: 1-3, 5
waitFor object

When the page counts as loaded, before it is printed or captured.

networkIdle object

auto waits for the load event, the fonts and the requests still running, and for half a second of network idle only on a URL or a document with scripts of its own. true always waits for that half second, false never does.

oneOf
boolean
selectorstringnullable

Wait until an element matching this CSS selector exists and is visible.

Default value: null
timeoutMsinteger

How long to wait for selector, in milliseconds, at most 30,000; then the render fails with render_timeout.

Possible values: >= 0

Default value: 5000
delayMsinteger

An extra pause after everything else, in milliseconds; a value above 10,000 counts as 10,000.

Possible values: >= 0

Default value: 0
tailwindboolean

Compile the Tailwind utility classes the document uses, for templates and plain html alike.

Default value: false
pdf object

PDF output only: what the file says about itself, and its structure for assistive technology.

metadata object

The document properties. The title is what a PDF reader shows in its title bar and a screen reader announces first; PDF/UA-1 requires one.

titlestring

Rendered with the data like the template, so it may use template expressions. Applies to stored templates and to html with an engine; a plain html or url render ignores it, so give such a page a <title> instead.

Example: Rechnung {{ invoice.number }}
authorstring

Rendered with the data like title for stored templates and html with an engine; written as given for plain html, url and Word and PowerPoint templates.

Example: Fennlor Studio GmbH
subjectstring

Rendered like author.

keywordsstring

Rendered like author, as one text; left out of the file when it comes out empty.

taggedboolean

Writes the structure tree (headings, lists, tables, links) a screen reader reads the document by.

Default value: false
outlineboolean

Writes bookmarks from the headings.

Default value: false
ua objectnullable

Makes the file a PDF/UA-1 document (ISO 14289-1): tagged, repaired where the browser's output breaks the standard, and held against veraPDF's machine-checkable rules of PDF/UA-1. true is { "check": "strict" }. The render carries the verdict as accessibility, and the file names itself PDF/UA-1 only when it passed. A passed check does not make a document accessible: alternative texts, reading order and contrast are in the template. Cannot be combined with post.merge_after, and is not available for Word and PowerPoint templates; each answers 400 invalid_request. With an e-invoice the file is a PDF/A-3b and a PDF/UA-1 document at once: both are checked in the file that is delivered, and the render carries both reports. false in a request switches off what the template declares. Asked for by a request whose output is an image, it answers 400 too; declared by an image template it is ignored. No plan limit and no extra unit.

oneOf
boolean
image object

Image output (png, jpg, webp): the browser window the page is captured in.

widthinteger

Window width in CSS pixels; 1200 by default.

Example: 1200
heightinteger

Window height in CSS pixels; 630 by default.

Example: 630
deviceScaleFactornumber

Pixel density: 2 makes a 1200 × 630 window a 2400 × 1260 image.

Default value: 2
formatstring

Output of an image template when the request names no output. jpg is accepted as well.

Possible values: [png, jpeg, webp]

qualityinteger

JPEG and WebP quality; 90 by default.

Possible values: >= 1 and <= 100

fullPageboolean

Capture the whole height of the page instead of the window.

Default value: false
transparentboolean

Transparent background (PNG).

Default value: false
clipSelectorstringnullable

CSS selector of one element to capture instead of the window; the first match counts. When none appears within 30 seconds, the render fails with render_timeout.

Default value: null
office object

Word and PowerPoint templates. Page setup, margins, headers and footers come from the document; the Chromium settings above do not apply.

outputstring

Output when the request names none; the template's own format without it.

Possible values: [docx, pptx, pdf]

localestring

BCP 47 tag that formats dates and numbers, picks the translation dictionary and sets <html lang>; en-GB by default.

Example: de-DE
timezonestring

IANA time zone for dates; Europe/Berlin by default.

Example: Europe/Berlin
currencystring

ISO 4217 code the money helper uses when none is given; EUR by default.

Example: EUR
einvoice objectnullable

Makes the template an invoice template: every PDF rendered from it is a ZUGFeRD / Factur-X e-invoice built from the _invoice block of the data, as if the request said post.einvoice. A request's settings.einvoice and post.einvoice merge over it field by field; post.einvoice: false switches it off for one request. Image output of the same template is not affected. false in a request switches off what the template declares.

oneOf

What kind of e-invoice a render makes. Every field has a default, so {} asks for a Factur-X invoice in the EN 16931 profile.

profilestring

en16931 carries every field of the European standard; basic is the smallest profile that is an invoice on its own. Any other profile answers 422 einvoice_profile_unsupported.

Possible values: [basic, en16931]

Default value: en16931
flavourstring

ZUGFeRD and Factur-X are one specification under two names, and the file is the same. The choice decides the name and release the render reports (Factur-X 1.09 or ZUGFeRD 2.5).

Possible values: [factur-x, zugferd]

Default value: factur-x
xmlstring

both stores the XML as a file of its own beside the PDF, kept and deleted with it; the render links it as einvoice.xml_url.

Possible values: [embedded, both]

Default value: embedded
display_checkstring

What happens when the PDF does not show a value of the XML (the invoice number, the totals): warn reports it in einvoice.display.missing, strict fails the render with 422 einvoice_display_mismatch.

Possible values: [warn, strict]

Default value: warn
design object

The visual editor's layers of an image template, stored with a version. Authoring data only: renders use the version's HTML and CSS, which the editor writes from it, and a render request's design is ignored. Kept as it is when you copy a version; at most 256 kB. See the visual editor guide.

property name*any

The visual editor's layers of an image template, stored with a version. Authoring data only: renders use the version's HTML and CSS, which the editor writes from it, and a render request's design is ignored. Kept as it is when you copy a version; at most 256 kB. See the visual editor guide.

property name*any

Rendering settings. A request's settings are deep-merged over the template's, which are merged over the defaults: only the keys you send change, and a section set to null (such as footer: null) is removed. The settings reference explains each key with examples.

sample_data object

Data the editor previews with, and from which a schema is inferred where none is stored. Never used by an API render.

property name*any

Data the editor previews with, and from which a schema is inferred where none is stored. Never used by an API render.

data_schema objectnullable

JSON Schema of data, which validate_data, the schema check of publishing and the integrations' fields use.

property name*anynullable

JSON Schema of data, which validate_data, the schema check of publishing and the integrations' fields use.

i18n objectnullable

Translation dictionaries: locale → key → text, read by the t helper.

property name*anynullable

Translation dictionaries: locale → key → text, read by the t helper.

partials object

Partials the template includes (name → source), as formfeed templates push collects them from the project's partials folder. At most 100 and 2 MB together; a name is a relative path of up to 200 characters without ...

property name*string

Possible values: <= 1048576 characters

data_sets object

Named sample data sets besides sample_data (name → data, names up to 100 characters), as the editor shows them and formfeed templates push sends them from data/*.json. At most 50.

property name*any

Named sample data sets besides sample_data (name → data, names up to 100 characters), as the editor shows them and formfeed templates push sends them from data/*.json. At most 50.

tagsstring[]

Up to 20 tags of up to 40 characters.

Possible values: <= 20

publishboolean

Publish version 1 at once.

Default value: false
TemplateCreate
{
  "name": "string",
  "slug": "invoice-de",
  "description": "string",
  "kind": "pdf",
  "engine": "jinja2",
  "html": "string",
  "css": "string",
  "head": "string",
  "settings": {
    "paper": {
      "format": "A4",
      "width": "100mm",
      "height": "150mm",
      "landscape": false
    },
    "margin": {
      "top": "20mm",
      "right": "15mm",
      "bottom": "20mm",
      "left": "15mm"
    },
    "header": {
      "html": "string",
      "height": "string",
      "padding": "0 10mm"
    },
    "footer": {
      "html": "string",
      "height": "string",
      "padding": "0 10mm"
    },
    "printBackground": true,
    "scale": 1,
    "preferCssPageSize": false,
    "pageRanges": "1-3, 5",
    "waitFor": {
      "networkIdle": true,
      "selector": null,
      "timeoutMs": 5000,
      "delayMs": 0
    },
    "tailwind": false,
    "pdf": {
      "metadata": {
        "title": "Rechnung {{ invoice.number }}",
        "author": "Fennlor Studio GmbH",
        "subject": "string",
        "keywords": "string"
      },
      "tagged": false,
      "outline": false,
      "ua": true
    },
    "image": {
      "width": 1200,
      "height": 630,
      "deviceScaleFactor": 2,
      "format": "png",
      "quality": 0,
      "fullPage": false,
      "transparent": false,
      "clipSelector": null
    },
    "office": {
      "output": "docx"
    },
    "locale": "de-DE",
    "timezone": "Europe/Berlin",
    "currency": "EUR",
    "einvoice": {
      "profile": "en16931",
      "flavour": "factur-x",
      "xml": "embedded",
      "display_check": "warn"
    },
    "design": {}
  },
  "sample_data": {},
  "data_schema": {},
  "i18n": {},
  "partials": {},
  "data_sets": {},
  "tags": [
    "string"
  ],
  "publish": false
}