Validate a template

POST

/v1/templates/validate

curl -H "X-Api-Key: $KEY" -F template=@letter.docx \
  http://localhost:9027/v1/templates/validate

import { openAsBlob } from 'node:fs';

const form = new FormData();
form.append('template', await openAsBlob('letter.docx'), 'letter.docx');

const response = await fetch('http://localhost:9027/v1/templates/validate', {
  method: 'POST',
  headers: { 'X-Api-Key': process.env.KEY },
  body: form,
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());

import os

import requests

response = requests.post(
    "http://localhost:9027/v1/templates/validate",
    headers={"X-Api-Key": os.environ["KEY"]},
    files=[("template", open("letter.docx", "rb"))],
)
response.raise_for_status()
print(response.json())

package main

import (
  "bytes"
  "io"
  "log"
  "mime/multipart"
  "net/http"
  "os"
  "path/filepath"
)

func main() {
  var body bytes.Buffer
  form := multipart.NewWriter(&body)
  attach(form, "template", "letter.docx")
  form.Close()

  request, err := http.NewRequest("POST", "http://localhost:9027/v1/templates/validate", &body)
  if err != nil {
    log.Fatal(err)
  }
  request.Header.Set("X-Api-Key", os.Getenv("KEY"))
  request.Header.Set("Content-Type", form.FormDataContentType())

  response, err := http.DefaultClient.Do(request)
  if err != nil {
    log.Fatal(err)
  }
  defer response.Body.Close()
  if response.StatusCode >= 300 {
    message, _ := io.ReadAll(response.Body)
    log.Fatalf("%s: %s", response.Status, message)
  }
  if _, err := io.Copy(os.Stdout, response.Body); err != nil {
    log.Fatal(err)
  }
}

// attach adds the file at path to the form as the named field.
func attach(form *multipart.Writer, field, path string) {
  file, err := os.Open(path)
  if err != nil {
    log.Fatal(err)
  }
  defer file.Close()
  part, err := form.CreateFormFile(field, filepath.Base(path))
  if err != nil {
    log.Fatal(err)
  }
  if _, err := io.Copy(part, file); err != nil {
    log.Fatal(err)
  }
}

const response = await fetch('http://localhost:9027/v1/templates/validate', {
  method: 'POST',
  headers: {
    'X-Api-Key': process.env.KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ templateId: 'letter' }),
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());

import os

import requests

response = requests.post(
    "http://localhost:9027/v1/templates/validate",
    headers={"X-Api-Key": os.environ["KEY"]},
    json={"templateId": "letter"},
)
response.raise_for_status()
print(response.json())

package main

import (
  "io"
  "log"
  "net/http"
  "os"
  "strings"
)

func main() {
  body := strings.NewReader(`{"templateId":"letter"}`)

  request, err := http.NewRequest("POST", "http://localhost:9027/v1/templates/validate", body)
  if err != nil {
    log.Fatal(err)
  }
  request.Header.Set("X-Api-Key", os.Getenv("KEY"))
  request.Header.Set("Content-Type", "application/json")

  response, err := http.DefaultClient.Do(request)
  if err != nil {
    log.Fatal(err)
  }
  defer response.Body.Close()
  if response.StatusCode >= 300 {
    message, _ := io.ReadAll(response.Body)
    log.Fatalf("%s: %s", response.Status, message)
  }
  if _, err := io.Copy(os.Stdout, response.Body); err != nil {
    log.Fatal(err)
  }
}

Checks a template against sample data without converting anything.

Authorizations

api_key
bearer
basic

Request Body^required

The multipart form /v1/render, /v1/render/batch and /v1/templates/validate accept.

object

assets

Images (PNG, JPEG, GIF, SVG), stylesheets and fonts an HTML page names by file name, as in <img src="logo.png">. Every stylesheet applies to the whole page. Nothing is fetched from anywhere else.

Array<string>

batchName

For /v1/render/batch: each file’s name, as a template.

string | null

bookmarks

For bookmarks: a JSON array of {"title", "page", "children"} that replaces the outline, sent as text.

Array<object> | null

object

certify

For sign: certify with DocMDP permission 1, 2 or 3 instead of approving.

integer | null format: int32

contactInfo

For sign: how to reach the signer.

string | null

ctx

JSON object visible as ctx, sent as text or as a file.

string | null

currency

The currency currency uses when given none, such as EUR. Wins over the template’s.

string | null

data

JSON object the template sees as its root, sent as text or as a file.

string | null

Example

{"customer": {"name": "Ada"}}

downloadFrom

Files to fetch from URLs instead of uploading them, as a JSON array of {"url": "..."} sent as text. At most 10 entries.

Array<object> | null

object

embeds

For embed: the files to attach.

Array<string>

embedsMetadata

For embed: a JSON object mapping a file name to {"mimeType": "..."}, sent as text.

object | null

facturxConformanceLevel

For factur-x: MINIMUM, BASIC_WL, BASIC, EN16931 (default) or EXTENDED.

string | null

facturxXml

For factur-x: the invoice XML to embed.

string format: binary

files

Further files, used by merge.

Array<string>

flatten

With a PDF template and data, true fixes the filled values into the page.

boolean | null

fonts

Fonts for this request only.

Array<string>

htmlEngine

What turns HTML into PDF: fulgur (default), a layout engine with no browser and no network, or libreoffice.

string | null

Example

fulgur

keep

What an Office template’s result may keep of what rendering takes out, comma-separated: macros, objects (OLE objects and ActiveX controls), externalLinks, privateLinks (hyperlinks to private addresses), or all. Default: none of them.

string | null

Example

privateLinks

lang

The language, such as fr, fr-CA or en-us, in any case. It wins over the template’s lang: it picks translations for t, and when CLDR has data for it, how number, currency and date write numbers, money and month names.

string | null

Example

fr-CA

level

For sign: b-b, b-t, b-lt or b-lta, as on /v1/pdf/sign.

string | null

location

For sign: where it was signed.

string | null

metadata

JSON object of metadata fields for metadata, sent as text.

string | null

outputFilename

File name of the result, without extension.

string | null

ownerPassword

For encrypt: the password that lifts its restrictions. Defaults to userPassword.

string | null

page

For a visible sign: the 1-based page. Default 1.

integer | null format: int32

pdfa

PDF/A level for pdfa: PDF/A-1b, PDF/A-2b, PDF/A-3b.

string | null

reason

For sign: why the document was signed.

string | null

rotateAngle

For rotate: 90 (default), 180, 270 or -90.

string | null

rotatePages

For rotate: the pages to turn, such as 1-3. Default all.

string | null

signatureImage

For sign: a PNG or JPEG to show the signature with, at page, x, y and width. With x and y and no image, the signature is shown as text: the signer, the date and the reason.

string format: binary

signerName

For sign: the signer’s name as shown.

string | null

signingKey

For sign: a named key instead of the default one.

string | null

splitBy

For /v1/render/batch: the array to render once per element.

string | null

splitMode

For split: pages (default) or intervals.

string | null

splitSpan

For split: page ranges such as 1-3,5 with pages, or a page count with intervals. Required by the step.

string | null

splitUnify

For split with pages: true gives one document holding the pages instead of one per range.

boolean | null

stamp

For stamp with an image or pdf source: the files to draw. At most five marks a request.

Array<string>

stampExpression

For stamp with a text source: the text to draw.

string | null

stampOptions

For stamp: a JSON object of pos, op, rot, sc, fontsize and fillc, each value a string, sent as text.

object | null

stampPages

For stamp: the pages to mark, such as 1-3. Default all.

string | null

stampSource

For stamp: what to draw over the page content, text, image or pdf.

string | null

steps

Comma-separated steps, run in the order given: convert, pdfa, pdfua, merge, split, watermark, stamp, underlay, rotate, flatten, optimize, bookmarks, metadata, embed, factur-x, encrypt, sign. Each reads the fields described as its own. sign signs cryptographically with the service’s key; it must be last and cannot be combined with encrypt.

string | null

Example

convert,pdfa,encrypt

stripAnnotations

With a PDF template and data, false keeps the annotations that held tags. They are removed by default.

boolean | null

template

The template file. Send this or templateId.

string format: binary

templateHash

The hex SHA-256 of a template this caller sent recently, in place of the file.

string | null

templateId

The id of a stored template, from POST /v1/templates, or an alias as name or name@version. Send this or template. Files in the form are then only further inputs, for merge.

string | null

timezone

The time zone date shows moments in: an offset such as +02:00, or an IANA zone such as Europe/Paris. Wins over the template’s.

string | null

Example

Europe/Paris

Output format for convert. Default pdf.

string | null

translations

Translations for t, by language, each a flat object of keys and texts. They win over the service’s dictionaries and the template’s own. At most 10,000 entries, keys of 256 bytes and texts of 16 KiB.

object | null

undefinedAsEmpty

true prints a value missing from the data as nothing instead of failing the render. Default false, so a misspelt name is an error.

boolean | null

underlay

For underlay: the PDF the document is laid over, page by page, such as letterhead or a pre-printed form.

string format: binary

userPassword

For encrypt: the password that opens the document.

string | null

watermark

For watermark with an image or pdf source: the files to draw. At most five marks a request.

Array<string>

watermarkExpression

For watermark with a text source: the text to draw.

string | null

watermarkOptions

For watermark: a JSON object of pos, op, rot, sc, fontsize and fillc, each value a string, sent as text.

object | null

watermarkPages

For watermark: the pages to mark, such as 1-3. Default all.

string | null

watermarkSource

For watermark: what to draw under the page content, text, image or pdf.

string | null

width

For a visible sign: width in points. Default the image’s natural size, or 200 for text.

number | null format: float

For a visible sign: points from the page’s left edge.

number | null format: float

For a visible sign: points from the page’s bottom edge.

number | null format: float

The JSON body /v1/render, /v1/render/batch and /v1/templates/validate accept with Content-Type: application/json, for a stored template: there are no files to send. Every text field of the multipart form is accepted under the same name, with the same meaning and limits; objects such as data and metadata are sent as JSON rather than as text, and steps may be a list. Fields that carry files cannot be sent.

object

batchName

For /v1/render/batch: each file’s name, as a template.

string | null

ctx

The object visible as ctx.

currency

The currency currency uses when given none, such as EUR. Wins over the template’s.

string | null

data

The object the template sees as its root.

downloadFrom

URLs to fetch as further inputs, as on the multipart form.

Array<object> | null

object

htmlEngine

fulgur (default) or libreoffice, for HTML.

string | null

keep

string | null

Example

privateLinks

lang

string | null

Example

fr-CA

metadata

Metadata fields for metadata.

outputFilename

File name of the result, without extension.

string | null

ownerPassword

string | null

pdfa

PDF/A level for pdfa.

string | null

splitBy

For /v1/render/batch: the array to render once per element.

string | null

steps

The steps in order, as a list or as comma-separated text.

Array<string> | null

Example

[
  "convert",
  "pdfa"
]

templateId

required

The stored template: its id, or an alias as name or name@version.

string

Example

invoice

timezone

The time zone date shows moments in: an offset such as +02:00, or an IANA zone such as Europe/Paris. Wins over the template’s.

string | null

Example

Europe/Paris

Output format for convert. Default pdf.

string | null

translations

object | null

undefinedAsEmpty

true prints a value missing from the data as nothing.

boolean | null

userPassword

string | null

Responses

200

The validation result

application/json

object

diagnostics

required

Every problem found: severity, message, and a location with part, place and snippet where known.

Array<object>

object

engine

required

The engine that would handle it: office, text or none.

string

error

The first error, when ok is false.

string | null

format

required

string

missing_fonts

required

Fonts the template names that the service has neither loaded nor mapped to a substitute with the same metrics. Text set in them renders in a fallback font, which moves line and page breaks. Each also appears in diagnostics as a warning.

Array<string>

required

True when the template renders with the sample data.

boolean

template_hash

required

SHA-256 of the template, the cache key.

string

Example ^generated

{
  "diagnostics": [
    {}
  ],
  "engine": "example",
  "error": "example",
  "format": "example",
  "missing_fonts": [
    "example"
  ],
  "ok": true,
  "template_hash": "example"
}

400

The request is wrong

application/json

The JSON body of every error response.

object

error

required

A stable, machine-readable kind.

string

message

required

What went wrong, for a person.

string

Example

{
  "error": "invalid_request",
  "message": "unknown step 'teleport'"
}

Validate a template

Authorizations

Request Bodyrequired

Example

Example

Example

Example

Example

Example

Example

Example

Example

Example

Example

Responses

200

Example generated

400

Example

Request Body^required

Example ^generated