---
title: "Create a batch"
method: POST
path: "/v1/batches"
tags: ["Batches"]
---

# Create a batch

`POST /v1/batches`

## Request

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

Renders one template version for many items — a JSON `items` array (≤ 25 MB body) or a CSV from `POST /v1/uploads` with an optional `csv_mapping` — sharing `output`, `delivery` and `webhook`. Items become ordinary renders (`source: batch`), released under your plan's bulk concurrency; `combine` adds a ZIP of all outputs and/or one merged PDF. Answers `202` right away; follow progress with `GET /v1/batches/{id}` or the `batch.progress` / `batch.completed` webhooks. Live items are billed as they are released: if the render limit is reached mid-batch, the batch pauses (`paused`, one `batch.progress`) and resumes on its own once renders are available again.

## Headers

- `Idempotency-Key` string

## Request body

- BatchRequest
  - `combine` CombineSpec
    - `merged_pdf` boolean
    - `zip` boolean
    - `zip_filename` string, nullable
  - `csv_mapping` object, nullable
  - `csv_upload_id` string, nullable
  - `delivery` 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`.
  - `engine` string, nullable
  - `items` BatchItemSpec[], nullable
    - `data` object
    - `filename` string, nullable
    - `metadata` object, nullable
    - `reference` string, nullable
  - `metadata` object, nullable
  - `output` OutputSpec
    - `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.
              - …
            - `base_amount` union: Decimal as a string (recommended) or a JSON number.
              - …
            - `percent` union: Decimal as a string (recommended) or a JSON 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.
              - …
            - `base_amount` union: Decimal as a string (recommended) or a JSON number.
              - …
            - `percent` union: Decimal as a string (recommended) or a JSON 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.
              - …
            - `buyer_id` string: BT-156 Item buyer's identifier.
            - `classifications` object[]: BT-158 Item classification identifiers.
              - …
            - `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
              - …
          - `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.
              - …
            - `base_unit` string: BT-150 Item price base quantity unit of measure code.
            - `discount` union: Decimal as a string (recommended) or a JSON number.
              - …
            - `gross` union: Decimal as a string (recommended) or a JSON number.
              - …
            - `net` union, required: Decimal as a string (recommended) or a JSON 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.
              - …
          - `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`).
    - `filename` string, nullable
    - `format` 'pdf' | 'png' | 'jpeg' | 'webp' | 'html', nullable
    - `image` ImageOptions
      - `clip_selector` string, nullable
      - `fit` 'contain' | 'cover' | 'fill', nullable
      - `format_options` FormatOptions
        - `lossless` boolean, nullable
        - `progressive` boolean, nullable
        - `quality` integer, nullable
      - `full_page` boolean, nullable
      - `height` integer, nullable
      - `omit_background` boolean, nullable
      - `scale` number, nullable
      - `transparent` boolean, nullable
      - `viewport` Viewport
        - `height` integer, required
        - `width` integer, required
      - `wait` Wait
        - `delay_ms` integer, nullable
        - `selector` string, nullable
        - `strict` boolean, nullable
        - `timeout_ms` integer, nullable
        - `until` 'load' | 'networkidle' | 'selector' | 'ready_flag' | 'delay', nullable
      - `width` integer, nullable
    - `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
  - `reference` string, nullable
  - `template_id` string, required
  - `test` boolean, nullable
  - `version` union
    - 'live'
    - integer
  - `webhook` BatchWebhookSpec
    - `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.

## Response `202`

Batch accepted (`Location: /v1/batches/{id}`).

- Batch
  - `canceled` integer
  - `combine` object
    - `merged_pdf` boolean
    - `zip` boolean
    - `zip_filename` string, nullable
  - `completed_at` string, date-time, nullable
  - `created_at` string, date-time, required
  - `emails` BatchEmailCounts: The newest email of each item and rule, by status (a resend replaces the email it repeats): `pending` includes `sending` and `retrying`, `sent` includes `sandboxed`.
    - `canceled` integer, required
    - `failed` integer, required
    - `pending` integer, required
    - `sent` integer, required
    - `skipped` integer, required
    - `unknown` integer, required
  - `error` object, nullable: Set when a requested combined file failed, which fails the batch: that file's error (the ZIP's first). `null` otherwise. `item_files_expired`: the files of succeeded items expired or were deleted before they could be combined; the combined files hold every succeeded item or none.
    - `code` string, required
    - `items` integer[]: `item_files_expired`: indexes of the items whose files are gone, ascending, at most 100.
    - `message` string, required
  - `failed` integer
  - `files` BatchFile[], required
    - `bytes` integer, required
    - `content_type` string, required
    - `expires_at` string, date-time, nullable: When the hosted file is deleted.
    - `file_id` string, required
    - `filename` string, required
    - `kind` 'zip' | 'merged_pdf', required
    - `pages` integer, nullable: Merged PDF only.
    - `url` string, uri: Signed URL (omitted when not hosted).
    - `url_expires_at` string, date-time
  - `id` string, required
  - `metadata` object
  - `object` 'batch', required
  - `paused` object, nullable: Set while the batch waits for renders: no item is released until a render pack, a plan change or the next cycle makes renders available again, then the batch resumes on its own (checked about once a minute). Items in flight finish normally; canceling works as usual. `null` otherwise.
    - `reason` 'render_limit_reached', required
    - `since` string, date-time, required
  - `pending` integer: Items without a final status yet.
  - `progress` number: Finished items ÷ total.
  - `reference` string, nullable
  - `status` 'queued' | 'processing' | 'completed' | 'failed' | 'canceled', required
  - `succeeded` integer
  - `template_id` string
  - `template_version` integer, nullable: Version number rendered.
  - `test` boolean, required
  - `total` integer, required

## Other responses

- `400`: Invalid request, items or CSV (`errors[]` with `/items/<i>/…` or `/csv/row/<n>`).
- `401`: Missing, invalid, expired or revoked credentials.
- `402`: Batches not on your plan, or render limit reached (`render_limit_reached`).
- `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, version or upload not found.
- `409`: A request with this Idempotency-Key is still in progress.
- `410`: Template deleted.
- `413`: Body over 25 MB or an item's data over 1 MB.
- `422`: Item data does not match the template schema, or the webhook URL is not allowed.
- `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)