---
title: "Generate a document asynchronously"
method: POST
path: "/api/documents/generate-async"
tags: ["Documents"]
---

# Generate a document asynchronously

`POST /api/documents/generate-async`

## Request

- Base URL: `https://api.dokmatiq.com`
- URL: `https://api.dokmatiq.com/api/documents/generate-async`
- Auth: API key in header `X-API-Key`

Submits a document generation request for asynchronous processing. Returns a job ID that can be used to poll status and download the result.

## Headers

- `X-DocGen-Validate` string

## Request body

- DocumentRequest: Request to generate a single document
  - `htmlContent` string: HTML content to render
  - `outputFormat` 'PDF' | 'DOCX' | 'ODT', required: Output format
  - `templateName` string: Name of a LibreOffice template file (without path, pre-uploaded)
  - `templateBase64` string: Base64-encoded template file (alternative to templateName). Allows fully stateless operation without pre-uploading templates.
  - `templateFilename` string: Original filename of the inline template (used to detect format: .odt, .ott, .docx)
  - `fields` object: Field placeholders to replace in the template (key = placeholder name, value = replacement text)
  - `bookmarks` object: Bookmark positions for HTML content injection (key = bookmark name, value = HTML)
  - `pageSettings` PageSettings: Page layout settings for the generated document
    - `headerLeft` string: Left-aligned header text (supports {{PAGE}} and {{PAGES}} placeholders)
    - `headerCenter` string: Center-aligned header text
    - `headerRight` string: Right-aligned header text
    - `footerLeft` string: Left-aligned footer text
    - `footerCenter` string: Center-aligned footer text
    - `footerRight` string: Right-aligned footer text
    - `header` HeaderFooterConfig: Header or footer configuration for a page style. Supports placeholders: {{PAGE}} (current page), {{PAGES}} (total pages), {{DATE}} (current date), {{TIME}} (current time), {{DATETIME}} (date and time), {{FILENAME}} (document filename).
      - `left` string: Left-aligned text
      - `center` string: Center-aligned text
      - `right` string: Right-aligned text
      - `height` integer: Height of the header/footer area in mm. If omitted, LibreOffice uses its default auto-height.
      - `spacing` integer: Spacing between the header/footer and the body text in mm
      - `fontName` string: Font name
      - `fontSize` number, float: Font size in points
      - `color` string: Text color as hex (RGB)
    - `footer` HeaderFooterConfig: Header or footer configuration for a page style. Supports placeholders: {{PAGE}} (current page), {{PAGES}} (total pages), {{DATE}} (current date), {{TIME}} (current time), {{DATETIME}} (date and time), {{FILENAME}} (document filename).
      - `left` string: Left-aligned text
      - `center` string: Center-aligned text
      - `right` string: Right-aligned text
      - `height` integer: Height of the header/footer area in mm. If omitted, LibreOffice uses its default auto-height.
      - `spacing` integer: Spacing between the header/footer and the body text in mm
      - `fontName` string: Font name
      - `fontSize` number, float: Font size in points
      - `color` string: Text color as hex (RGB)
    - `headerFirstPage` HeaderFooterConfig: Header or footer configuration for a page style. Supports placeholders: {{PAGE}} (current page), {{PAGES}} (total pages), {{DATE}} (current date), {{TIME}} (current time), {{DATETIME}} (date and time), {{FILENAME}} (document filename).
      - `left` string: Left-aligned text
      - `center` string: Center-aligned text
      - `right` string: Right-aligned text
      - `height` integer: Height of the header/footer area in mm. If omitted, LibreOffice uses its default auto-height.
      - `spacing` integer: Spacing between the header/footer and the body text in mm
      - `fontName` string: Font name
      - `fontSize` number, float: Font size in points
      - `color` string: Text color as hex (RGB)
    - `footerFirstPage` HeaderFooterConfig: Header or footer configuration for a page style. Supports placeholders: {{PAGE}} (current page), {{PAGES}} (total pages), {{DATE}} (current date), {{TIME}} (current time), {{DATETIME}} (date and time), {{FILENAME}} (document filename).
      - `left` string: Left-aligned text
      - `center` string: Center-aligned text
      - `right` string: Right-aligned text
      - `height` integer: Height of the header/footer area in mm. If omitted, LibreOffice uses its default auto-height.
      - `spacing` integer: Spacing between the header/footer and the body text in mm
      - `fontName` string: Font name
      - `fontSize` number, float: Font size in points
      - `color` string: Text color as hex (RGB)
    - `headerEvenPages` HeaderFooterConfig: Header or footer configuration for a page style. Supports placeholders: {{PAGE}} (current page), {{PAGES}} (total pages), {{DATE}} (current date), {{TIME}} (current time), {{DATETIME}} (date and time), {{FILENAME}} (document filename).
      - `left` string: Left-aligned text
      - `center` string: Center-aligned text
      - `right` string: Right-aligned text
      - `height` integer: Height of the header/footer area in mm. If omitted, LibreOffice uses its default auto-height.
      - `spacing` integer: Spacing between the header/footer and the body text in mm
      - `fontName` string: Font name
      - `fontSize` number, float: Font size in points
      - `color` string: Text color as hex (RGB)
    - `footerEvenPages` HeaderFooterConfig: Header or footer configuration for a page style. Supports placeholders: {{PAGE}} (current page), {{PAGES}} (total pages), {{DATE}} (current date), {{TIME}} (current time), {{DATETIME}} (date and time), {{FILENAME}} (document filename).
      - `left` string: Left-aligned text
      - `center` string: Center-aligned text
      - `right` string: Right-aligned text
      - `height` integer: Height of the header/footer area in mm. If omitted, LibreOffice uses its default auto-height.
      - `spacing` integer: Spacing between the header/footer and the body text in mm
      - `fontName` string: Font name
      - `fontSize` number, float: Font size in points
      - `color` string: Text color as hex (RGB)
    - `headerFooterFontName` string: Default font name for all headers and footers. Individual header/footer configs can override this.
    - `headerFooterFontSize` number, float: Default font size (pt) for all headers and footers. Individual header/footer configs can override this.
    - `headerFooterColor` string: Default text color for all headers and footers (hex RGB). Individual header/footer configs can override this.
    - `orientation` 'PORTRAIT' | 'LANDSCAPE': Page orientation
    - `paperSize` 'A4' | 'A3' | 'A5' | 'LETTER' | 'LEGAL': Paper size
    - `marginTop` integer: Top margin in mm
    - `marginBottom` integer: Bottom margin in mm
    - `marginLeft` integer: Left margin in mm
    - `marginRight` integer: Right margin in mm
    - `pageNumberOffset` integer: Page number offset. The first page will be numbered as this value. For example, set to 3 to start counting at page 3 (useful for documents that are part of a larger document set).
  - `watermark` WatermarkConfig: Watermark configuration. Can be a simple string (just the text) or an object with text, fontSize, opacity, and color properties.
    - `text` string: Watermark text
    - `fontSize` number, float: Font size in points. If not set, the text is auto-scaled to fill ~75% of the page diagonal.
    - `opacity` number, float: Opacity from 0.0 (invisible) to 1.0 (fully opaque). Default: 0.15
    - `color` string: Color as hex string (e.g. '#999999'). Default: '#999999'
  - `password` string: Password to protect the output document
  - `images` object: Images to embed at bookmark positions (key = bookmark name)
  - `qrCodes` object: QR codes to generate at bookmark positions (key = bookmark name)
  - `barcodes` object: Barcodes to generate at bookmark positions (key = bookmark name). Supports CODE128, CODE39, EAN13, EAN8, UPC_A, ITF, CODABAR formats.
  - `tables` object: Tables to generate at bookmark positions (key = bookmark name)
  - `markdownContent` string: Markdown content to render (alternative to htmlContent). Converted to native LibreOffice elements with proper styles.
  - `markdownBookmarks` object: Markdown content at bookmark positions (key = bookmark name, value = Markdown text)
  - `markdownStyles` MarkdownStyles: Custom style mapping for Markdown elements. Each field maps a Markdown element to a LibreOffice paragraph or character style name defined in the template. If omitted, sensible defaults are used (e.g. 'Heading 1' for h1).
    - `heading1` string: Paragraph style for # headings
    - `heading2` string: Paragraph style for ## headings
    - `heading3` string: Paragraph style for ### headings
    - `heading4` string: Paragraph style for #### headings
    - `heading5` string: Paragraph style for ##### headings
    - `heading6` string: Paragraph style for ###### headings
    - `paragraph` string: Paragraph style for normal text paragraphs
    - `listBullet` string: Paragraph style for unordered list items
    - `listNumber` string: Paragraph style for ordered list items
    - `listBullet2` string: Paragraph style for nested unordered list items
    - `listNumber2` string: Paragraph style for nested ordered list items
    - `codeBlock` string: Paragraph style for code blocks
    - `blockQuote` string: Paragraph style for block quotes
    - `codeSpan` string: Character style for inline code spans
    - `codeFontName` string: Font name for inline code (used if no codeSpan style)
  - `contentAreas` ContentArea[]: Positioned content areas placed at absolute coordinates from the page edge. Ideal for address fields, date lines, reference numbers on letterheads. Only for PDF output.
    - `content` string: Text content with optional inline markup. Supports line breaks via \n, **bold**, *italic*, and ***bold+italic***.
    - `x` number, float, required: Horizontal position in mm from the left page edge
    - `y` number, float, required: Vertical position in mm from the top page edge
    - `width` number, float, required: Maximum width in mm. Text wraps at this boundary.
    - `height` number, float: Maximum height in mm. Content exceeding this is clipped. If omitted, no vertical clipping is applied.
    - `fontName` string: Font name. Built-in: Helvetica, Times-Roman, Courier. Custom fonts can be referenced by family name (uploaded via /api/fonts) or provided inline via the customFonts field.
    - `customFonts` object: Inline custom fonts as Base64-encoded TTF/OTF data. Keys: 'regular', 'bold', 'italic', 'boldItalic'. At minimum 'regular' should be provided; missing variants fall back to regular. If omitted, the fontName is looked up from uploaded fonts or built-in fonts.
    - `fontSize` number, float: Font size in points
    - `lineHeight` number, float: Line height as multiplier of font size
    - `color` string: Text color as hex (RGB)
    - `bold` boolean: Bold text
    - `alignment` 'LEFT' | 'CENTER' | 'RIGHT': Text alignment within the content area
    - `pages` string: Which pages this content area appears on. Single number = that page only (e.g. '1', '3'). Number with '+' = from that page onwards (e.g. '2+'). Range = specific range (e.g. '2-4'). 'all' = every page. Default: first page only.
    - `barcode` BarcodeData: Barcode to generate at a bookmark position
      - `content` string, required: Content to encode in the barcode
      - `format` string: Barcode format: CODE128, CODE39, EAN13, EAN8, UPC_A, ITF, CODABAR
      - `width` integer: Barcode width in mm
      - `height` integer: Barcode height in mm
      - `showText` boolean: Show human-readable text below the barcode
    - `imageBase64` string: Base64-encoded image (PNG, JPG, etc.) to render at the given coordinates. When set, the content field is ignored and the image is placed at x/y with the given width/height.
  - `stationery` StationeryConfig: Stationery (letterhead) PDF overlay configuration. The provided PDF is placed as a background layer under the generated content, like printing on pre-printed company stationery. Only applies to PDF output.
    - `pdf` string, required: Base64-encoded stationery PDF used for all pages. If firstPagePdf is also provided, this is used for pages 2+.
    - `firstPagePdf` string: Base64-encoded stationery PDF used only for the first page. When set, the main 'pdf' field is used for all following pages. Useful when the first page has a full letterhead and following pages have a simpler header.
  - `invoice` InvoiceData: ZUGFeRD/Factur-X invoice data to embed in a PDF
    - `profile` 'MINIMUM' | 'BASICWL' | 'BASIC' | 'EN16931' | 'EXTENDED' | 'XRECHNUNG': ZUGFeRD profile
    - `number` string, required: Invoice number
    - `date` string, required: Invoice date (ISO format)
    - `dueDate` string: Due date (ISO format)
    - `currency` string: Currency code (ISO 4217)
    - `seller` Party, required: Trade party (seller or buyer)
      - `name` string, required: Company or person name
      - `street` string, required: Street address
      - `zip` string, required: ZIP / postal code
      - `city` string, required: City
      - `country` string: Country code (ISO 3166-1 alpha-2)
      - `vatId` string: VAT identification number
      - `email` string: Email address
      - `phone` string: Phone number
    - `buyer` Party, required: Trade party (seller or buyer)
      - `name` string, required: Company or person name
      - `street` string, required: Street address
      - `zip` string, required: ZIP / postal code
      - `city` string, required: City
      - `country` string: Country code (ISO 3166-1 alpha-2)
      - `vatId` string: VAT identification number
      - `email` string: Email address
      - `phone` string: Phone number
    - `items` InvoiceItem[], required: Invoice line items
      - `description` string, required: Item description
      - `quantity` number, required: Quantity
      - `unit` 'HUR' | 'C62' | 'KGM' | 'MTR' | 'LTR' | 'DAY': Unit code (UN/ECE Rec 20)
      - `unitPrice` number, required: Unit price (net)
      - `vatRate` number, required: VAT rate in percent
    - `paymentTerms` string: Payment terms description
    - `bankAccount` BankAccount: Bank account details for payment
      - `iban` string, required: IBAN
      - `bic` string: BIC/SWIFT code
      - `accountHolder` string: Account holder name
    - `referenceNumber` string: Reference number (e.g. Leitweg-ID for XRechnung)
    - `buyerReference` string: Buyer reference (Leitweg-ID), required for XRechnung
    - `invoiceTypeCode` '380' | '381' | '384' | '389': Invoice type code (UN/CEFACT 1001)
    - `sellerTaxNumber` string: Seller tax number (Steuernummer, alternative to VAT ID)
    - `paymentMeansCode` string: Payment means code (UN/CEFACT 4461)
    - `xrechnungFormat` 'CII' | 'UBL': XRechnung output format (CII or UBL)
  - `callbackUrl` string: Webhook callback URL for async jobs. When set, DocGen sends a POST request to this URL when the job completes or fails. The payload contains jobId, status, downloadUrl, file size, duration, and error details.
  - `callbackSecret` string: Optional secret for HMAC-SHA256 webhook signature. When set, each webhook request includes an X-DocGen-Signature header for payload verification.

## Response `202`

Job accepted

## Other responses

- `500`: Failed to submit job

---

[API](https://skmtc.dev/dokmatiq/apis/docgen-api.md) · [All operations](https://skmtc.dev/dokmatiq/apis/docgen-api/llms.txt) · [OpenAPI document](https://skmtc.dev/dokmatiq/apis/docgen-api/revisions/3fa1a922764d?raw)