PDF options

PDF options control how a page is printed: its size, margins, what is waited for and what metadata the file carries. Send them as output.pdf in a render request, or as pdf in the convenience endpoints.

{
  "input": { "type": "template", "template_id": "tpl_01J9ZK3M7Q8V5W2X4Y6Z8A0B1C" },
  "data": { "number": "2026-0042" },
  "output": {
    "format": "pdf",
    "pdf": {
      "paper": { "size": "A4" },
      "margin": { "top": "20mm", "right": "15mm", "bottom": "20mm", "left": "15mm" },
      "print_background": true
    }
  }
}

Templates store their own defaults, set in the editor's Options tab. Options you send with a request override the template's defaults.

A PDF template can also store a default e-invoice, einvoice: {"profile": "EN16931", "invoice_path": "invoice"} next to pdf in its options, set in the Options tab under E-invoice (ZUGFeRD / Factur-X). Every render of it is then a Factur-X / ZUGFeRD PDF/A-3b unless the request sends its own output.einvoice, or "einvoice": null to render a plain PDF. On plans without e-invoicing it is skipped with the warning einvoice_skipped_plan. See Make a template an e-invoice by default.

Page setup

Paper sizes

Custom sizes are useful for labels and receipts:

{ "paper": { "width": "4in", "height": "6in" } }

CSS length units

Sizes and margins are CSS length strings with an explicit unit:

For example "20mm", "0.75in" and "48px" are valid; a bare number is not.

Content and print behaviour

Backgrounds only print when the element also allows it in CSS. Add print-color-adjust: exact (with the -webkit- prefixed property for older engines) to elements with coloured backgrounds.

Headers and footers

header and footer take the same fields. Headers and footers explains both modes in detail.

Accessibility and archiving

PDF/A

PDF/A (ISO 19005) is the standard for PDFs that must stay readable for decades, such as invoices, contracts and statements. Set pdfa and the engine converts the printed PDF, then validates it with veraPDF:

{
  "input": { "type": "template", "template_id": "tpl_01J9ZK3M7Q8V5W2X4Y6Z8A0B1C" },
  "data": { "number": "2026-0042" },
  "output": {
    "format": "pdf",
    "pdf": { "pdfa": "2b", "metadata": { "title": "Invoice 2026-0042", "lang": "de-DE" } }
  }
}

The conversion adds an sRGB output intent and writes the PDF/A identification and the document metadata into XMP. It doesn't render the page again, so text, images and layout stay as printed. PDF/A output costs no additional renders. It is included in the Growth plan and higher; on Free and Starter, pdfa fails with 402 plan_feature_unavailable.

What to know:

• Fonts must be embedded. If a font can't be embedded, the render fails with 422 pdfa_conversion_failed and the message names the font.
• No encryption. PDF/A forbids it, so protect together with pdfa fails with 400 validation_error.
• Report. result.conformance.pdfa on the render holds the level, the status (passed, failed or unavailable) and any findings. If veraPDF finds the file non-compliant, the render fails with pdfa_conversion_failed, costs nothing, and the failed rules are listed in the report. See validation report.
• Unavailable validator. If veraPDF doesn't answer in time, the file is delivered unvalidated, with the warning pdfa_validation_unavailable and status: "unavailable".
• Test renders. The TEST watermark is drawn as vector outlines and stamped before the conversion, so a test PDF is conformant too and the report describes the delivered file.

Convert an existing PDF

POST /v1/pdf-tools/pdfa converts a PDF that wasn't rendered by Dynamic Document API and validates the result:

curl https://api-eu.dynamicdocumentapi.com/v1/pdf-tools/pdfa \
  -H "Authorization: Bearer $DYNAMIC_DOCUMENT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "source": { "url": "https://example.com/contract.pdf" }, "level": "2b", "filename": "contract-pdfa.pdf" }'

The response is a render with the converted file and the report in result.conformance.pdfa. It accepts the same mode, delivery, webhook, reference, metadata and test fields as the other PDF tools. Conversion is best effort: it can't embed fonts the source doesn't contain, and it can't process encrypted PDFs. Either fails with pdfa_conversion_failed. A conversion is billed as 1 render, and failed ones cost nothing. Like pdfa, this endpoint needs the Growth plan or higher.

PDF/UA

PDF/UA (ISO 14289-1) is the standard for accessible PDFs: screen readers and other assistive technology can read them in the right order, with headings, lists, tables, link texts and image descriptions. Set pdfua to "1" and the render either delivers a PDF that passes veraPDF's PDF/UA-1 checks or fails:

{
  "input": { "type": "template", "template_id": "tpl_01J9ZK3M7Q8V5W2X4Y6Z8A0B1C" },
  "data": { "number": "2026-0042" },
  "output": {
    "format": "pdf",
    "pdf": { "pdfua": "1", "metadata": { "title": "Invoice 2026-0042", "lang": "en-GB" } }
  }
}

After rendering, Dynamic Document API fixes what the browser's tagging leaves open: link descriptions, list structure, headers and footers marked as artifacts that screen readers skip, and the PDF/UA identification. What only your template can provide:

• A title and a language. Set metadata.title or a <title> element, and metadata.lang or <html lang>. With pdfua there is no default language: a document without one fails the check.
• Text alternatives. alt text on meaningful images, and alt="" on decorative ones.
• Structure. Real tables with <th scope>, headings in order, and lists as <ul> or <ol>.

Content that is hidden from the accessibility tree (aria-hidden, alt="", CSS content, borders) becomes a decoration that screen readers skip, so meaningful text belongs in the markup.

What to know:

• Report. result.conformance.pdfua holds the standard, the status (passed, failed or unavailable) and the rules that failed. A render that fails the check fails with 422 pdfua_validation_failed and the report, and costs nothing.
• Unavailable validator. If veraPDF doesn't answer in time, the file is delivered unvalidated, with the warning pdfua_validation_unavailable and status: "unavailable".
• Limits of the check. veraPDF checks what a machine can check. Whether alt text is meaningful and the reading order is right is yours to review.
• Combinations. pdfua works with pdfa, e-invoices, attachments and protect, which keeps access for assistive technology. PDFs from canvas templates can't be PDF/UA (400 validation_error).
• Previews and publishing. Editor previews show the report but never fail. Publishing warns when the template's test render fails the check.
• Plan. PDF/UA is included in the Growth plan and higher; on Free and Starter, pdfua fails with 402 plan_feature_unavailable.

Attachments

attachments embeds files in the PDF, for example the supporting documents of an invoice. Each entry has:

{
  "output": {
    "format": "pdf",
    "pdf": {
      "attachments": [
        { "url": "https://example.com/timesheet.csv", "name": "timesheet.csv", "relationship": "Supplement" }
      ]
    }
  }
}

Up to 20 files, each at most 10 MiB and 25 MiB together. A file that can't be fetched fails the render with 422 attachment_failed, which names it.

Attachments work with plain PDFs and with pdfa: "3b", where they sit next to an e-invoice's XML. pdfa: "2b" can't carry them (400 validation_error), and an attachment can't take the name of the embedded e-invoice (factur-x.xml, xrechnung.xml). With protect, the files are embedded before encryption. Editor previews and test renders leave attachments out. Uploads expire after 24 hours, so a template's default attachments use url or data_uri.

Metadata

Security

Protecting a document restricts editing, not reading: a permission you leave out keeps its default. To protect an existing PDF, use the protect tool.

Documents are encrypted with AES-256. Passwords are part of the request body, so keep them out of logs on your side and use request-log redaction rules if you enable request logging. Protection can't be combined with pdfa or an e-invoice, because PDF/A forbids encryption. With pdfua, protection keeps the permission that lets assistive technology read the text.

Waiting and scripting

Rendering starts once the page is ready. Choose a strategy that matches how your page loads:

After the wait condition, the renderer always waits for web fonts to load and images to decode before printing, so a fixed delay is rarely necessary. When a wait step times out, the render continues with the page as it is and records a warning, so check the render's warnings if output looks incomplete. A render that cannot continue fails with 422 wait_timeout.

For pages that build content with JavaScript, such as charts, set the ready flag when you are done:

<script>
  renderChart(data).then(() => {
    window.__DYNAMIC_DOCUMENT_API_READY__ = true;
  });
</script>

{ "wait": { "until": "ready_flag", "timeout_ms": 20000 } }

Examples

An A4 invoice with a footer and metadata:

{
  "paper": { "size": "A4" },
  "margin": { "top": "18mm", "right": "16mm", "bottom": "22mm", "left": "16mm" },
  "print_background": true,
  "footer": {
    "enabled": true,
    "html": "<div style=\"width:100%;padding:0 16mm;display:flex;justify-content:space-between;font-size:8pt;color:#555\"><span>Example GmbH</span><span>Page <span class=\"page\"></span> of <span class=\"pages\"></span></span></div>",
    "height": "14mm"
  },
  "metadata": { "title": "Invoice 2026-0042", "author": "Example GmbH", "lang": "de-DE" }
}

An 80 mm receipt on one continuous page, where the declared height is replaced by the content height:

{
  "paper": { "width": "80mm", "height": "200mm" },
  "margin": { "top": "4mm", "right": "4mm", "bottom": "4mm", "left": "4mm" },
  "single_page": true
}

A landscape report with bookmarks and a tagged structure:

{
  "paper": { "size": "A3" },
  "orientation": "landscape",
  "scale": 0.9,
  "outline": true,
  "tagged": true,
  "metadata": { "title": "Quarterly report", "lang": "en-GB" }
}

A shipping label at 4 × 6 inches, printed edge to edge:

{
  "paper": { "width": "4in", "height": "6in" },
  "margin": { "top": "0mm", "right": "0mm", "bottom": "0mm", "left": "0mm" },
  "print_background": true
}

A protected document with printing allowed but copying and editing blocked:

{
  "paper": { "size": "A4" },
  "protect": {
    "user_password": "…",
    "owner_password": "…",
    "permissions": { "print": true, "copy": false, "modify": false }
  }
}

Related pages

• Headers and footers for running headers, page numbers and logos
• Pagination basics for page breaks, repeating table headers and layout problems
• Image and screenshot options for PNG and JPEG output
• E-invoicing for Factur-X, ZUGFeRD and XRechnung
• PDF tools for merging, splitting, protecting and converting existing PDFs