---
title: "PDF from HTML"
method: POST
path: "/v1/pdf/from-html"
tags: ["Renders"]
---

# PDF from HTML

`POST /v1/pdf/from-html`

## Request

- Base URL: `https://api-eu.dynamicdocumentapi.com`
- URL: `https://api-eu.dynamicdocumentapi.com/v1/pdf/from-html`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Convenience wrapper over `POST /v1/renders` with flat, no-code friendly fields.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `data` object, nullable
  - `data_url` string, nullable
  - `delivery` union
    - DeliverySpec
      - `email` union: Email rules (Growth plan and up). Absent or `null`: the template's enabled rules; `false`: none; a list: only those rules, optionally with literal `to`/`cc`/`bcc`. Template renders only (not previews, signed links, PDF tools or zero-retention renders).
        - false
        - EmailTargetSpec[]
          - `bcc` string[], nullable: Replaces the rule's `bcc` (`[]`: none).
          - `cc` string[], nullable: Replaces the rule's `cc` (`[]`: none).
          - `rule_id` string, required: An enabled email rule (`emr_…`) of the render's template.
          - `to` string[], nullable: Literal recipients instead of the rule's `to`: each entry one address or `Name <address>`.
      - `expires_in` integer
      - `hosted` boolean, nullable: Keep the hosted copy; `false` deletes it once the storage uploads and email sends have succeeded. Absent or `null`: `false` when every storage destination of the render has `keep_hosted_copy: false`, else `true`. Zero-retention renders never keep one.
      - `retention` 'none' | 'default', nullable
      - `retention_days` integer, nullable
      - `storage` StorageTargetSpec[], nullable
        - `destination_id` string, required
        - `path` string, nullable
      - `type` 'url' | 'binary' | 'base64' | 'none', nullable: `url`: signed file URLs in the response; `binary` / `base64`: the file itself (sync only); `none`: no file in the response (storage destinations, email). Absent or `null`: `url` when the render keeps a hosted copy, else `none`.
    - 'url' | 'binary' | 'base64' | 'none'
  - `einvoice` EInvoiceSpec: `output.einvoice`: embed a Factur-X / ZUGFeRD / XRechnung invoice in a PDF/A-3b (hybrid PDF).
    - `invoice` Invoice: Invoice data for `output.einvoice.invoice` and `POST /v1/einvoices`. Semantic model of EN 16931-1:2017 with snake_case names; every field names its business term (BT-n) or group (BG-n). Amounts are decimal strings (numbers are accepted) in the invoice currency with at most 2 decimals; quantities and prices allow up to 6 decimals. Derived values (line net amounts BT-131, the VAT breakdown BG-23 and the document totals BG-22) are computed by the engine and must not be sent, except `net_amount` on a line, which is checked when present.
      - `allowances` InvoiceDocumentAllowanceCharge[]: BG-20 Document level allowances (BT-92…BT-98).
        - `amount` union, required: Decimal as a string (recommended) or a JSON number.
          - string
          - number
        - `base_amount` union: Decimal as a string (recommended) or a JSON number.
          - string
          - number
        - `percent` union: Decimal as a string (recommended) or a JSON number.
          - string
          - number
        - `reason` string: BT-97/BT-104 Reason (text).
        - `reason_code` string: BT-98/BT-105 Reason code (UNTDID 5189 for allowances, 7161 for charges).
        - `tax_category` 'S' | 'Z' | 'E' | 'AE' | 'K' | 'G' | 'O' | 'L' | 'M', required: VAT category code (UNTDID 5305 subset of EN 16931): S standard, Z zero rated, E exempt, AE reverse charge, K intra-community supply, G export outside the EU, O not subject to VAT, L Canary Islands IGIC, M Ceuta/Melilla IPSI.
        - `tax_rate` union: Decimal as a string (recommended) or a JSON number.
          - string
          - number
      - `buyer` InvoiceBuyer, required: BG-7 Buyer.
        - `address` InvoiceAddress, required
          - `city` string: BT-37/BT-52/BT-66/BT-77 City.
          - `country` string, required: ISO 3166-1 alpha-2 country code.
          - `line1` string: BT-35/BT-50/BT-64/BT-75 Address line 1.
          - `line2` string: BT-36/BT-51/BT-65/BT-76 Address line 2.
          - `line3` string: BT-162/BT-163/BT-164/BT-165 Address line 3.
          - `postcode` string: BT-38/BT-53/BT-67/BT-78 Post code.
          - `subdivision` string: BT-39/BT-54/BT-68/BT-79 Country subdivision.
        - `contact` InvoiceContact
          - `email` string: BT-43/BT-58 Contact e-mail address.
          - `name` string: BT-41/BT-56 Contact point (person or department).
          - `phone` string: BT-42/BT-57 Contact telephone number.
        - `electronic_address` InvoiceIdentifier
          - `id` string, required
          - `scheme` string: Scheme identifier: ISO 6523 ICD for party identifiers (e.g. 0088 GLN), EAS for electronic addresses (e.g. EM e-mail, 9930 German VAT, 0204 Leitweg-ID).
        - `identifiers` InvoiceIdentifier[]: BT-29 Seller identifier(s) / BT-46 Buyer identifier (one) with ISO 6523 ICD scheme.
          - `id` string, required
          - `scheme` string: Scheme identifier: ISO 6523 ICD for party identifiers (e.g. 0088 GLN), EAS for electronic addresses (e.g. EM e-mail, 9930 German VAT, 0204 Leitweg-ID).
        - `legal_registration` InvoiceIdentifier
          - `id` string, required
          - `scheme` string: Scheme identifier: ISO 6523 ICD for party identifiers (e.g. 0088 GLN), EAS for electronic addresses (e.g. EM e-mail, 9930 German VAT, 0204 Leitweg-ID).
        - `name` string, required: BT-27/BT-44 Name.
        - `trading_name` string: BT-28/BT-45 Trading name.
        - `vat_id` string: BT-31/BT-48 VAT identifier with ISO 3166-1 country prefix, e.g. DE123456789.
      - `buyer_accounting_reference` string: BT-19 Buyer accounting reference.
      - `buyer_reference` string: BT-10 Buyer reference (the Leitweg-ID for German public buyers; mandatory for XRECHNUNG).
      - `charges` InvoiceDocumentAllowanceCharge[]: BG-21 Document level charges (BT-99…BT-105).
        - `amount` union, required: Decimal as a string (recommended) or a JSON number.
          - string
          - number
        - `base_amount` union: Decimal as a string (recommended) or a JSON number.
          - string
          - number
        - `percent` union: Decimal as a string (recommended) or a JSON number.
          - string
          - number
        - `reason` string: BT-97/BT-104 Reason (text).
        - `reason_code` string: BT-98/BT-105 Reason code (UNTDID 5189 for allowances, 7161 for charges).
        - `tax_category` 'S' | 'Z' | 'E' | 'AE' | 'K' | 'G' | 'O' | 'L' | 'M', required: VAT category code (UNTDID 5305 subset of EN 16931): S standard, Z zero rated, E exempt, AE reverse charge, K intra-community supply, G export outside the EU, O not subject to VAT, L Canary Islands IGIC, M Ceuta/Melilla IPSI.
        - `tax_rate` union: Decimal as a string (recommended) or a JSON number.
          - string
          - number
      - `contract_reference` string: BT-12 Contract reference.
      - `currency` string, required: BT-5 Invoice currency code (ISO 4217).
      - `delivery` object: BG-13 Delivery information.
        - `address` InvoiceAddress
          - `city` string: BT-37/BT-52/BT-66/BT-77 City.
          - `country` string, required: ISO 3166-1 alpha-2 country code.
          - `line1` string: BT-35/BT-50/BT-64/BT-75 Address line 1.
          - `line2` string: BT-36/BT-51/BT-65/BT-76 Address line 2.
          - `line3` string: BT-162/BT-163/BT-164/BT-165 Address line 3.
          - `postcode` string: BT-38/BT-53/BT-67/BT-78 Post code.
          - `subdivision` string: BT-39/BT-54/BT-68/BT-79 Country subdivision.
        - `date` string: Calendar date, YYYY-MM-DD.
        - `location` InvoiceIdentifier
          - `id` string, required
          - `scheme` string: Scheme identifier: ISO 6523 ICD for party identifiers (e.g. 0088 GLN), EAS for electronic addresses (e.g. EM e-mail, 9930 German VAT, 0204 Leitweg-ID).
        - `party_name` string: BT-70 Deliver to party name.
      - `despatch_advice_reference` string: BT-16 Despatch advice reference.
      - `due_date` string: Calendar date, YYYY-MM-DD.
      - `invoice_period` InvoicePeriod
        - `end` string: Calendar date, YYYY-MM-DD.
        - `start` string: Calendar date, YYYY-MM-DD.
      - `invoiced_object` InvoiceIdentifier
        - `id` string, required
        - `scheme` string: Scheme identifier: ISO 6523 ICD for party identifiers (e.g. 0088 GLN), EAS for electronic addresses (e.g. EM e-mail, 9930 German VAT, 0204 Leitweg-ID).
      - `issue_date` string, required: Calendar date, YYYY-MM-DD.
      - `lines` InvoiceLine[], required: BG-25 Invoice lines. Always required: MINIMUM and BASIC_WL do not transmit lines, but the totals are computed from them.
        - `accounting_reference` string: BT-133 Invoice line buyer accounting reference.
        - `allowances` InvoiceLineAllowanceCharge[]: BG-27 Invoice line allowances.
          - `amount` union, required: Decimal as a string (recommended) or a JSON number.
            - string
            - number
          - `base_amount` union: Decimal as a string (recommended) or a JSON number.
            - string
            - number
          - `percent` union: Decimal as a string (recommended) or a JSON number.
            - string
            - number
          - `reason` string: BT-139/BT-144 Reason (text).
          - `reason_code` string: BT-140/BT-145 Reason code (UNTDID 5189 / 7161).
        - `charges` InvoiceLineAllowanceCharge[]: BG-28 Invoice line charges.
          - `amount` union, required: Decimal as a string (recommended) or a JSON number.
            - string
            - number
          - `base_amount` union: Decimal as a string (recommended) or a JSON number.
            - string
            - number
          - `percent` union: Decimal as a string (recommended) or a JSON number.
            - string
            - number
          - `reason` string: BT-139/BT-144 Reason (text).
          - `reason_code` string: BT-140/BT-145 Reason code (UNTDID 5189 / 7161).
        - `id` string: BT-126 Invoice line identifier (default: the 1-based position).
        - `item` object, required: BG-31 Item information.
          - `attributes` object[]: BG-32 Item attributes.
            - `name` string, required: BT-160 Item attribute name.
            - `value` string, required: BT-161 Item attribute value.
          - `buyer_id` string: BT-156 Item buyer's identifier.
          - `classifications` object[]: BT-158 Item classification identifiers.
            - `id` string, required
            - `scheme` string, required: UNTDID 7143 list id, e.g. HS (Harmonized System), STI or TST; ids outside the list are rejected (BR-CL-13).
            - `version` string
          - `description` string: BT-154 Item description.
          - `name` string, required: BT-153 Item name.
          - `origin_country` string: ISO 3166-1 alpha-2 country code.
          - `seller_id` string: BT-155 Item seller's identifier.
          - `standard_id` InvoiceIdentifier
            - `id` string, required
            - `scheme` string: Scheme identifier: ISO 6523 ICD for party identifiers (e.g. 0088 GLN), EAS for electronic addresses (e.g. EM e-mail, 9930 German VAT, 0204 Leitweg-ID).
        - `net_amount` union: Decimal as a string (recommended) or a JSON number.
          - string
          - number
        - `note` string: BT-127 Invoice line note.
        - `object_identifier` InvoiceIdentifier
          - `id` string, required
          - `scheme` string: Scheme identifier: ISO 6523 ICD for party identifiers (e.g. 0088 GLN), EAS for electronic addresses (e.g. EM e-mail, 9930 German VAT, 0204 Leitweg-ID).
        - `order_line_reference` string: BT-132 Referenced purchase order line reference.
        - `period` InvoicePeriod
          - `end` string: Calendar date, YYYY-MM-DD.
          - `start` string: Calendar date, YYYY-MM-DD.
        - `price` object, required: BG-29 Price details.
          - `base_quantity` union: Decimal as a string (recommended) or a JSON number.
            - string
            - number
          - `base_unit` string: BT-150 Item price base quantity unit of measure code.
          - `discount` union: Decimal as a string (recommended) or a JSON number.
            - string
            - number
          - `gross` union: Decimal as a string (recommended) or a JSON number.
            - string
            - number
          - `net` union, required: Decimal as a string (recommended) or a JSON number.
            - string
            - number
        - `quantity` union, required: Decimal as a string (recommended) or a JSON number.
          - string
          - number
        - `tax` object, required: BG-30 Line VAT information.
          - `category` 'S' | 'Z' | 'E' | 'AE' | 'K' | 'G' | 'O' | 'L' | 'M', required: VAT category code (UNTDID 5305 subset of EN 16931): S standard, Z zero rated, E exempt, AE reverse charge, K intra-community supply, G export outside the EU, O not subject to VAT, L Canary Islands IGIC, M Ceuta/Melilla IPSI.
          - `rate` union: Decimal as a string (recommended) or a JSON number.
            - string
            - number
        - `unit` string: BT-130 Unit of measure (UN/ECE Recommendation 20/21), e.g. C62 one, H87 piece, HUR hour, DAY day, KGM kilogram. Default C62.
      - `notes` object[]: BG-1 Invoice notes.
        - `subject_code` string: BT-21 Invoice note subject code (UNTDID 4451, e.g. AAI, REG, ABL, TXD).
        - `text` string, required: BT-22 Invoice note.
      - `number` string, required: BT-1 Invoice number.
      - `order_reference` string: BT-13 Purchase order reference.
      - `payee` object: BG-10 Payee, when different from the seller.
        - `identifier` InvoiceIdentifier
          - `id` string, required
          - `scheme` string: Scheme identifier: ISO 6523 ICD for party identifiers (e.g. 0088 GLN), EAS for electronic addresses (e.g. EM e-mail, 9930 German VAT, 0204 Leitweg-ID).
        - `legal_registration` InvoiceIdentifier
          - `id` string, required
          - `scheme` string: Scheme identifier: ISO 6523 ICD for party identifiers (e.g. 0088 GLN), EAS for electronic addresses (e.g. EM e-mail, 9930 German VAT, 0204 Leitweg-ID).
        - `name` string, required: BT-59 Payee name.
      - `payment` InvoicePayment: BG-16 Payment instructions (mandatory for XRECHNUNG).
        - `card` object: BG-18 Payment card information.
          - `account_number` string, required: BT-87 Payment card primary account number (only the last 4–6 digits).
          - `holder` string: BT-88 Payment card holder name.
        - `credit_transfers` object[]: BG-17 Credit transfer accounts.
          - `account_id` string, required: BT-84 Payment account identifier (IBAN for SEPA).
          - `account_name` string: BT-85 Payment account name.
          - `bic` string: BT-86 Payment service provider identifier (BIC).
        - `direct_debit` object: BG-19 Direct debit.
          - `creditor_id` string: BT-90 Bank assigned creditor identifier.
          - `debited_account` string: BT-91 Debited account identifier (IBAN).
          - `mandate_reference` string: BT-89 Mandate reference identifier.
        - `means_code` string, required: BT-81 Payment means type code (UNTDID 4461): 58 SEPA credit transfer, 30 credit transfer, 59 SEPA direct debit, 49 direct debit, 48 bank card, 54 credit card, 10 cash, 1 not defined, ZZZ mutually defined.
        - `means_text` string: BT-82 Payment means text.
        - `remittance_information` string: BT-83 Remittance information (payment reference).
      - `payment_terms` string: BT-20 Payment terms (free text; XRECHNUNG accepts the `#SKONTO#` syntax here).
      - `preceding_invoices` object[]: BG-3 Preceding invoice references (required for corrected invoices 384).
        - `issue_date` string: Calendar date, YYYY-MM-DD.
        - `number` string, required: BT-25 Preceding invoice reference.
      - `prepaid_amount` union: Decimal as a string (recommended) or a JSON number.
        - string
        - number
      - `process_id` string: BT-23 Business process type. Defaults for XRECHNUNG to `urn:fdc:peppol.eu:2017:poacc:billing:01:1.0`.
      - `project_reference` string: BT-11 Project reference.
      - `receiving_advice_reference` string: BT-15 Receiving advice reference.
      - `rounding_amount` union: Decimal as a string (recommended) or a JSON number.
        - string
        - number
      - `sales_order_reference` string: BT-14 Sales order reference.
      - `seller` InvoiceSeller, required: BG-4 Seller.
        - `address` InvoiceAddress, required
          - `city` string: BT-37/BT-52/BT-66/BT-77 City.
          - `country` string, required: ISO 3166-1 alpha-2 country code.
          - `line1` string: BT-35/BT-50/BT-64/BT-75 Address line 1.
          - `line2` string: BT-36/BT-51/BT-65/BT-76 Address line 2.
          - `line3` string: BT-162/BT-163/BT-164/BT-165 Address line 3.
          - `postcode` string: BT-38/BT-53/BT-67/BT-78 Post code.
          - `subdivision` string: BT-39/BT-54/BT-68/BT-79 Country subdivision.
        - `contact` InvoiceContact
          - `email` string: BT-43/BT-58 Contact e-mail address.
          - `name` string: BT-41/BT-56 Contact point (person or department).
          - `phone` string: BT-42/BT-57 Contact telephone number.
        - `electronic_address` InvoiceIdentifier
          - `id` string, required
          - `scheme` string: Scheme identifier: ISO 6523 ICD for party identifiers (e.g. 0088 GLN), EAS for electronic addresses (e.g. EM e-mail, 9930 German VAT, 0204 Leitweg-ID).
        - `identifiers` InvoiceIdentifier[]: BT-29 Seller identifier(s) / BT-46 Buyer identifier (one) with ISO 6523 ICD scheme.
          - `id` string, required
          - `scheme` string: Scheme identifier: ISO 6523 ICD for party identifiers (e.g. 0088 GLN), EAS for electronic addresses (e.g. EM e-mail, 9930 German VAT, 0204 Leitweg-ID).
        - `legal_info` string: BT-33 Seller additional legal information.
        - `legal_registration` InvoiceIdentifier
          - `id` string, required
          - `scheme` string: Scheme identifier: ISO 6523 ICD for party identifiers (e.g. 0088 GLN), EAS for electronic addresses (e.g. EM e-mail, 9930 German VAT, 0204 Leitweg-ID).
        - `name` string, required: BT-27/BT-44 Name.
        - `tax_number` string: BT-32 Seller tax registration identifier (local tax number, e.g. the German Steuernummer).
        - `trading_name` string: BT-28/BT-45 Trading name.
        - `vat_id` string: BT-31/BT-48 VAT identifier with ISO 3166-1 country prefix, e.g. DE123456789.
      - `supporting_documents` object[]: BG-24 Additional supporting documents (references only).
        - `description` string: BT-123 Supporting document description.
        - `id` string, required: BT-122 Supporting document reference.
        - `url` string: BT-124 External document location.
      - `tax_currency` string: BT-6 VAT accounting currency code (ISO 4217), when it differs from the invoice currency. Requires `tax_total_in_tax_currency`.
      - `tax_point_date` string: Calendar date, YYYY-MM-DD.
      - `tax_point_date_code` '3' | '35' | '432': BT-8 Value added tax point date code (UNTDID 2005): 3 invoice document issue date, 35 actual delivery date, 432 paid to date.
      - `tax_representative` object: BG-11 Seller tax representative party.
        - `address` InvoiceAddress, required
          - `city` string: BT-37/BT-52/BT-66/BT-77 City.
          - `country` string, required: ISO 3166-1 alpha-2 country code.
          - `line1` string: BT-35/BT-50/BT-64/BT-75 Address line 1.
          - `line2` string: BT-36/BT-51/BT-65/BT-76 Address line 2.
          - `line3` string: BT-162/BT-163/BT-164/BT-165 Address line 3.
          - `postcode` string: BT-38/BT-53/BT-67/BT-78 Post code.
          - `subdivision` string: BT-39/BT-54/BT-68/BT-79 Country subdivision.
        - `name` string, required: BT-62 Seller tax representative name.
        - `vat_id` string, required: BT-63 Seller tax representative VAT identifier (with ISO 3166-1 country prefix).
      - `tax_total_in_tax_currency` union: Decimal as a string (recommended) or a JSON number.
        - string
        - number
      - `tender_reference` string: BT-17 Tender or lot reference.
      - `type_code` string: BT-3 Invoice type code (UNTDID 1001): 380 commercial invoice (default), 381 credit note, 384 corrected invoice, 389 self-billed invoice, 326 partial invoice, 386 prepayment invoice, 751 invoice information for accounting purposes, 875/876/877 partial/partial final/final construction invoice.
      - `vat_exemptions` object: BT-120/BT-121 VAT exemption reason per VAT category code (BG-23), e.g. {"AE": {"reason": "Reverse charge", "reason_code": "vatex-eu-ae"}}. Required for categories E, AE, K, G, O (EN 16931 BR-E-10, BR-AE-10, BR-IC-10, BR-G-10, BR-O-10).
    - `invoice_path` string, nullable: Dotted path of object keys into `data` that holds the invoice model, e.g. `invoice` or `order.invoice` (each batch item resolves it in its own data).
    - `profile` 'MINIMUM' | 'BASIC_WL' | 'BASIC' | 'EN16931' | 'EXTENDED' | 'XRECHNUNG', required: Factur-X / ZUGFeRD profile, or `XRECHNUNG` (German CIUS, embedded as `xrechnung.xml`).
    - `syntax` 'cii' | 'ubl', nullable: Hybrid PDFs embed UN/CEFACT CII: omit or `"cii"` (UBL XML: `POST /v1/einvoices`).
  - `engine` string, nullable
  - `expires_in` integer
  - `filename` string: Jinja-enabled filename.
  - `head` string, nullable
  - `hosted` boolean, nullable: Keep the hosted copy; `false` deletes it once the storage uploads and email sends have succeeded. Absent or `null`: `false` when every storage destination of the render has `keep_hosted_copy: false`, else `true`. Zero-retention renders never keep one.
  - `html` string, required
  - `metadata` object, nullable
  - `mode` 'sync' | 'async'
  - `pdf` PdfOptions
    - `attachments` PdfAttachment[], nullable
      - `data_uri` string, nullable
      - `description` string, nullable
      - `mime_type` string, nullable
      - `name` string, required
      - `relationship` 'Source' | 'Data' | 'Alternative' | 'Supplement' | 'Unspecified', nullable
      - `upload_id` string, nullable
      - `url` string, nullable
    - `emulate_media` 'print' | 'screen', nullable
    - `footer` HeaderFooter
      - `center` string, nullable
      - `enabled` boolean
      - `font_size` string, nullable
      - `height` string, nullable
      - `html` string, nullable
      - `left` string, nullable
      - `right` string, nullable
    - `header` HeaderFooter
      - `center` string, nullable
      - `enabled` boolean
      - `font_size` string, nullable
      - `height` string, nullable
      - `html` string, nullable
      - `left` string, nullable
      - `right` string, nullable
    - `javascript` boolean, nullable
    - `locale` string, nullable
    - `margin` Margin
      - `bottom` string, nullable
      - `left` string, nullable
      - `right` string, nullable
      - `top` string, nullable
    - `metadata` PdfMetadata
      - `author` string, nullable
      - `creator` string, nullable
      - `keywords` string[]
      - `lang` string, nullable
      - `subject` string, nullable
      - `title` string, nullable
    - `orientation` 'portrait' | 'landscape', nullable
    - `outline` boolean, nullable
    - `page_ranges` string, nullable
    - `paper` Paper
      - `height` string, nullable
      - `size` 'A0' | 'A1' | 'A2' | 'A3' | 'A4' | 'A5' | 'A6' | 'B4' | 'B5' | 'Letter' | 'Legal' | 'Tabloid' | 'Ledger', nullable
      - `width` string, nullable
    - `pdfa` '2b' | '3b', nullable
    - `pdfua` '1', nullable: `"1"`: a PDF/UA-1 (ISO 14289-1) document, validated with veraPDF (report in `result.conformance.pdfua`); a file that fails validation fails the render with `pdfua_validation_failed`. Implies `tagged`; combines with `pdfa`, `einvoice`, `attachments` and `protect` (which keeps assistive-technology access). PDF output only, and not for canvas templates (their PDFs carry no tags); needs the Growth plan or higher. The document needs a title and a language: `metadata.title` and `metadata.lang`, or the page's `<title>` and `<html lang>`.
    - `prefer_css_page_size` boolean, nullable
    - `print_background` boolean, nullable
    - `protect` Protect
      - `owner_password` string, nullable
      - `permissions` Permissions: Permissions of a protected PDF. Protecting a document restricts editing, not reading: an omitted flag must never end up denied. `Permissions` on the wire has explicit presence per flag, and the renderer applies exactly these defaults to the ones a job leaves unset (`DEFAULT_PERMISSIONS` in `worker/bins/renderer/src/job.rs`) — the two lists must stay identical.
        - `annotate` boolean
        - `assemble` boolean
        - `copy` boolean
        - `fill_forms` boolean
        - `modify` boolean
        - `print` boolean
        - `print_high_res` boolean
      - `user_password` string, nullable
    - `scale` number, nullable
    - `single_page` boolean, nullable
    - `tagged` boolean, nullable: A tagged PDF (accessibility structure). Without `pdfua` the PDF/UA-1 report in `result.conformance.pdfua` is information only.
    - `timezone` string, nullable
    - `wait` Wait
      - `delay_ms` integer, nullable
      - `selector` string, nullable
      - `strict` boolean, nullable
      - `timeout_ms` integer, nullable
      - `until` 'load' | 'networkidle' | 'selector' | 'ready_flag' | 'delay', nullable
  - `priority` 'normal' | 'low'
  - `reference` string, nullable
  - `retention_days` integer, nullable
  - `templating` boolean, nullable
  - `test` boolean, nullable
  - `timeout_behavior` 'continue' | 'cancel'
  - `webhook` WebhookSpec
    - `events` string[]
    - `format` 'standard'
    - `url` string, required: Where to send the events: https (or http in test mode) with a public host and no credentials, on port 443, 80, 8080 or 8443.
  - `webhook_url` string, uri

## Response `200`

Sync render finished (`status=succeeded`). With `delivery.type=binary` the body is the file.

- Render
  - `batch_id` string, nullable
  - `billed_renders` integer: Renders billed for this request (0 for test renders, previews, failed and canceled renders).
  - `completed_at` string, date-time, nullable
  - `created_at` string, date-time, required
  - `email` RenderEmail[]: The render's email sends in creation order. They are created when the render's result is processed, so a render still running (or a sync response) lists none yet; `render.succeeded` shows them as created: `pending`, or `skipped` / `failed`.
    - `error` EmailSendError, required: Why a send failed or waits: never message bodies or addresses.
      - `code` string, required: `email_template_error`, `email_too_large`, `email_recipient_missing`, `email_address_invalid`, `email_too_many_recipients`, `email_attachment_too_large`, `email_attachment_type_not_allowed`, `email_needs_hosted_file`, `email_provider_rejected`, `email_provider_auth_failed`, `email_provider_unavailable`, `email_ip_not_authorized`, `email_rate_limited`, `email_outcome_unknown`, `email_daily_cap_reached`, `email_disabled`, `email_credentials_removed`, `email_send_expired`, `internal_error`
      - `column` integer
      - `field` string: `email_template_error`, `email_too_large`: the rule field, e.g. `subject`.
      - `line` integer: `email_template_error`: where in the field.
      - `message` string, required
      - `provider_code` string, nullable: The provider's own error code.
      - `provider_status` integer, nullable: The provider's HTTP or SMTP status.
    - `id` string, required
    - `provider_message_id` string, nullable, required
    - `rule_id` string, required
    - `sent_at` string, date-time, nullable, required
    - `status` 'pending' | 'sending' | 'retrying' | 'sent' | 'sandboxed' | 'skipped' | 'failed' | 'unknown' | 'canceled', required
    - `to` string[], required: The `to` addresses.
  - `engine` string
  - `engine_version` string, nullable
  - `error` RenderError
    - `code` string
    - `column` integer
    - `detail` string
    - `excerpt` string
    - `line` integer
    - `message` string
  - `expires_at` string, date-time, nullable
  - `files` RenderFile[], required
    - `bytes` integer, required
    - `content_base64` string: Only with `delivery.type=base64`.
    - `content_type` string
    - `filename` string, required
    - `format` 'pdf' | 'png' | 'jpeg' | 'webp' | 'html' | 'zip' | 'xml', required
    - `height` integer, nullable
    - `id` string, required
    - `pages` integer, nullable
    - `sha256` string
    - `url` string, uri: Signed URL (omitted when not hosted).
    - `url_expires_at` string, date-time
    - `variant` string, nullable
    - `width` integer, nullable
  - `id` string, required
  - `input_type` 'template' | 'html' | 'url' | 'markdown' | 'pdf_tool' | 'einvoice'
  - `kind` string
  - `metadata` object
  - `mode` 'sync' | 'async', required
  - `object` 'render', required
  - `output_format` 'pdf' | 'png' | 'jpeg' | 'webp' | 'html' | 'zip' | 'xml'
  - `pages` integer, nullable
  - `reference` string, nullable
  - `region` string, required
  - `result` RenderResult: Structured result, `null` for most renders. PDF/A, PDF/UA, tagged and e-invoice renders carry their conformance report here — succeeded **and** failed ones; `pdf-tools/metadata` without `set` returns the document information (`pages`, `page_sizes`, `encrypted`, `metadata`).
    - `conformance` ConformanceReport: Validation of the delivered file against the standards it claims.
      - `einvoice` EInvoiceConformance
        - `errors` ConformanceFinding[], required
          - `count` integer, required
          - `location` string, required: JSON path into the invoice for model issues found before the XML was written, else the validator's XPath or veraPDF context; empty when the finding concerns the whole document (e.g. a PDF/A `conversion` error).
          - `message` string, required
          - `rule` string, required: Business rule (EN 16931 `BR-…`, XRechnung `BR-DE-…`), schema rule, or PDF/A or PDF/UA clause and test number (`6.2.4.3-2`, `7.3-1`).
        - `profile` 'MINIMUM' | 'BASIC_WL' | 'BASIC' | 'EN16931' | 'EXTENDED' | 'XRECHNUNG', required
        - `scenario` string, nullable, required: The validator scenario that matched; `null` when it did not run.
        - `status` 'passed' | 'failed' | 'unavailable', required: `unavailable`: the validator was not configured or did not answer in time; the file was delivered unvalidated (warning `einvoice_validation_unavailable`).
        - `syntax` 'cii' | 'ubl', required
        - `validator` string, nullable, required: `null` when the validator did not run (`einvoice_invalid`: the model broke a rule before any XML was written, or unavailable).
        - `warnings` ConformanceFinding[], required
          - `count` integer, required
          - `location` string, required: JSON path into the invoice for model issues found before the XML was written, else the validator's XPath or veraPDF context; empty when the finding concerns the whole document (e.g. a PDF/A `conversion` error).
          - `message` string, required
          - `rule` string, required: Business rule (EN 16931 `BR-…`, XRechnung `BR-DE-…`), schema rule, or PDF/A or PDF/UA clause and test number (`6.2.4.3-2`, `7.3-1`).
      - `pdfa` PdfaConformance
        - `errors` ConformanceFinding[], required
          - `count` integer, required
          - `location` string, required: JSON path into the invoice for model issues found before the XML was written, else the validator's XPath or veraPDF context; empty when the finding concerns the whole document (e.g. a PDF/A `conversion` error).
          - `message` string, required
          - `rule` string, required: Business rule (EN 16931 `BR-…`, XRechnung `BR-DE-…`), schema rule, or PDF/A or PDF/UA clause and test number (`6.2.4.3-2`, `7.3-1`).
        - `level` '2b' | '3b', required
        - `profile` string, nullable, required: veraPDF validation profile; `null` when veraPDF did not run.
        - `status` 'passed' | 'failed' | 'unavailable', required: `unavailable`: the validator was not configured or did not answer in time; the file was delivered unvalidated (warning `pdfa_validation_unavailable`).
        - `validator` string, nullable, required: `null` when veraPDF did not run (conversion failed, or unavailable).
        - `warnings` ConformanceFinding[], required
          - `count` integer, required
          - `location` string, required: JSON path into the invoice for model issues found before the XML was written, else the validator's XPath or veraPDF context; empty when the finding concerns the whole document (e.g. a PDF/A `conversion` error).
          - `message` string, required
          - `rule` string, required: Business rule (EN 16931 `BR-…`, XRechnung `BR-DE-…`), schema rule, or PDF/A or PDF/UA clause and test number (`6.2.4.3-2`, `7.3-1`).
      - `pdfua` PdfuaConformance: veraPDF's PDF/UA-1 check of a render with `pdf.pdfua` or `pdf.tagged`. With `pdfua`, `failed` fails the render (`pdfua_validation_failed`); with `tagged` alone, and in previews, the report is information. The machine checks don't judge whether alt text is meaningful or the reading order right.
        - `errors` ConformanceFinding[], required
          - `count` integer, required
          - `location` string, required: JSON path into the invoice for model issues found before the XML was written, else the validator's XPath or veraPDF context; empty when the finding concerns the whole document (e.g. a PDF/A `conversion` error).
          - `message` string, required
          - `rule` string, required: Business rule (EN 16931 `BR-…`, XRechnung `BR-DE-…`), schema rule, or PDF/A or PDF/UA clause and test number (`6.2.4.3-2`, `7.3-1`).
        - `profile` string, nullable, required: veraPDF validation profile; `null` when veraPDF did not run.
        - `standard` 'PDF/UA-1', required
        - `status` 'passed' | 'failed' | 'unavailable', required: `unavailable`: the validator was not configured or did not answer in time; the file was delivered unvalidated (warning `pdfua_validation_unavailable`).
        - `validator` string, nullable, required: `null` when veraPDF did not run (the title or language was missing, or unavailable).
        - `warnings` ConformanceFinding[], required
          - `count` integer, required
          - `location` string, required: JSON path into the invoice for model issues found before the XML was written, else the validator's XPath or veraPDF context; empty when the finding concerns the whole document (e.g. a PDF/A `conversion` error).
          - `message` string, required
          - `rule` string, required: Business rule (EN 16931 `BR-…`, XRechnung `BR-DE-…`), schema rule, or PDF/A or PDF/UA clause and test number (`6.2.4.3-2`, `7.3-1`).
  - `source` string
  - `status` 'queued' | 'processing' | 'succeeded' | 'failed' | 'canceled' | 'expired', required
  - `storage` StorageResult[]
    - `destination_id` string
    - `error` string, nullable
    - `location` string, nullable
    - `status` 'pending' | 'succeeded' | 'failed' | 'skipped'
  - `template` object, nullable
    - `id` string
    - `version` union
      - integer
      - string
    - `version_id` string, nullable
  - `test` boolean, required
  - `timings` object
  - `warnings` object[]: Non-fatal: `slow_asset`, `asset_failed`, `wait_timeout` (the wait condition timed out and `wait.strict` is off, so the page was rendered as it was), `header_footer_overlap` (a header or footer is taller than its margin and may cover the body), `locale_unsupported` (the engine doesn't support `locale`), `feature_unavailable` (something in the request or template was ignored; the message names it), `font_fallback_used` (canvas templates: an unavailable font was replaced by Noto Sans; HTML renders fall back silently), `data_coerced` (canvas templates: a data value couldn't be used as given), `text_overflow` (canvas templates: text was cut off or overflows its box), `storage_upload_failed`, `einvoice_validation_warning`, `einvoice_validation_unavailable`, `pdfa_validation_unavailable`, `pdfua_validation_unavailable` (veraPDF was not reachable: the PDF/UA file is delivered unvalidated), `accessibility_validation_unavailable` (`tagged` without `pdfua`: no PDF/UA report, veraPDF was not reachable), `einvoice_skipped_plan`, `storage_skipped_plan`, `email_skipped_plan` (the template's email rules need the Growth plan or higher; no email was sent), `email_skipped_zero_retention` (zero-retention renders have no file to email), `invoice_totals_unavailable`.
    - `code` string
    - `message` string

## Other responses

- `202`: Async render accepted, or the sync timeout was exceeded (`Location: /v1/renders/{id}`).
- `400`: Malformed or invalid request (`errors[]` with JSON pointers), e.g. an unknown, switched-off or another template's rule at `/delivery/email/<i>/rule_id`.
- `401`: Missing, invalid, expired or revoked credentials.
- `402`: Render limit reached (`render_limit_reached`) or feature not on plan (`plan_feature_unavailable`, e.g. a `delivery.email` list below the Growth plan).
- `403`: Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified; or `region_not_enabled`: the workspace's enabled regions leave out this region.
- `404`: Template or version not found.
- `408`: Sync timeout exceeded and the render was canceled (`timeout_behavior=cancel`).
- `409`: A request with this Idempotency-Key is still in progress.
- `410`: Template deleted.
- `413`: Payload or output too large.
- `422`: Render failed (`render_id`, `render_error`; `render_failed` when the worker reports no more specific code), schema mismatch, URL not allowed or idempotency key reused. `einvoice_invalid`, `einvoice_validation_failed`, `pdfa_conversion_failed` and `pdfua_validation_failed` also carry the conformance report as `result`. `email_needs_hosted_file`: `delivery.email` lists rules, but a zero-retention render keeps no file to email. `render_canceled`: the sync render was canceled, or its job expired, before it finished. `scene_invalid`, `data_invalid`: a canvas template's scene can't be rendered (e.g. an output over 16,384 px per side), or its `data` isn't an object or lacks a required dynamic property.
- `429`: Rate limited (`Retry-After`).
- `503`: Region degraded (`Retry-After`).

---

[API](https://skmtc.dev/dynamicdocumentapi/apis/dynamic-document-api.md) · [All operations](https://skmtc.dev/dynamicdocumentapi/apis/dynamic-document-api/llms.txt) · [OpenAPI document](https://skmtc.dev/dynamicdocumentapi/apis/dynamic-document-api/revisions/0f14bc0000f4?raw)