Documents

Generate a document asynchronously

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

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

Headers

X-DocGen-Validatestring

Request body

htmlContentstring

HTML content to render

outputFormat'PDF' | 'DOCX' | 'ODT' required

Output format

templateNamestring

Name of a LibreOffice template file (without path, pre-uploaded)

templateBase64string

Base64-encoded template file (alternative to templateName). Allows fully stateless operation without pre-uploading templates.

templateFilenamestring

Original filename of the inline template (used to detect format: .odt, .ott, .docx)

fieldsobject

Field placeholders to replace in the template (key = placeholder name, value = replacement text)

bookmarksobject

Bookmark positions for HTML content injection (key = bookmark name, value = HTML)

passwordstring

Password to protect the output document

imagesobject

Images to embed at bookmark positions (key = bookmark name)

qrCodesobject

QR codes to generate at bookmark positions (key = bookmark name)

barcodesobject

Barcodes to generate at bookmark positions (key = bookmark name). Supports CODE128, CODE39, EAN13, EAN8, UPC_A, ITF, CODABAR formats.

tablesobject

Tables to generate at bookmark positions (key = bookmark name)

markdownContentstring

Markdown content to render (alternative to htmlContent). Converted to native LibreOffice elements with proper styles.

markdownBookmarksobject

Markdown content at bookmark positions (key = bookmark name, value = Markdown text)

callbackUrlstring

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.

callbackSecretstring

Optional secret for HMAC-SHA256 webhook signature. When set, each webhook request includes an X-DocGen-Signature header for payload verification.

Example request

{
  "htmlContent": "<h1>Hello</h1><p>World</p>",
  "templateName": "invoice-template.odt",
  "templateBase64": "UEsDBBQAAAAIAA...",
  "templateFilename": "rechnung.odt",
  "pageSettings": {
    "headerLeft": "Company Name",
    "headerCenter": "Document Title",
    "headerRight": "{{PAGE}}/{{PAGES}}",
    "footerCenter": "Page {{PAGE}} of {{PAGES}}",
    "header": {
      "left": "Company Name",
      "center": "Document Title",
      "right": "{{PAGE}} / {{PAGES}}",
      "height": 15,
      "spacing": 5,
      "fontName": "Helvetica",
      "fontSize": 9,
      "color": "#666666"
    },
    "footer": {
      "left": "Company Name",
      "center": "Document Title",
      "right": "{{PAGE}} / {{PAGES}}",
      "height": 15,
      "spacing": 5,
      "fontName": "Helvetica",
      "fontSize": 9,
      "color": "#666666"
    },
    "headerFirstPage": {
      "left": "Company Name",
      "center": "Document Title",
      "right": "{{PAGE}} / {{PAGES}}",
      "height": 15,
      "spacing": 5,
      "fontName": "Helvetica",
      "fontSize": 9,
      "color": "#666666"
    },
    "footerFirstPage": {
      "left": "Company Name",
      "center": "Document Title",
      "right": "{{PAGE}} / {{PAGES}}",
      "height": 15,
      "spacing": 5,
      "fontName": "Helvetica",
      "fontSize": 9,
      "color": "#666666"
    },
    "headerEvenPages": {
      "left": "Company Name",
      "center": "Document Title",
      "right": "{{PAGE}} / {{PAGES}}",
      "height": 15,
      "spacing": 5,
      "fontName": "Helvetica",
      "fontSize": 9,
      "color": "#666666"
    },
    "footerEvenPages": {
      "left": "Company Name",
      "center": "Document Title",
      "right": "{{PAGE}} / {{PAGES}}",
      "height": 15,
      "spacing": 5,
      "fontName": "Helvetica",
      "fontSize": 9,
      "color": "#666666"
    },
    "headerFooterFontName": "Helvetica",
    "headerFooterFontSize": 9,
    "headerFooterColor": "#666666",
    "marginTop": 20,
    "marginBottom": 20,
    "marginLeft": 25,
    "marginRight": 25,
    "pageNumberOffset": 1
  },
  "watermark": {
    "text": "DRAFT",
    "fontSize": 120,
    "opacity": 0.15
  },
  "password": "secret123",
  "markdownContent": "# Invoice\n\nDear **Mr. Smith**,\n\n- Item 1\n- Item 2\n\n| Product | Price |\n|---------|-------|\n| Widget  | 9.99  |",
  "markdownStyles": {
    "heading1": "Heading 1",
    "heading2": "Heading 2",
    "heading3": "Heading 3",
    "heading4": "Heading 4",
    "heading5": "Heading 5",
    "heading6": "Heading 6",
    "paragraph": "Text Body",
    "listBullet": "List Bullet",
    "listNumber": "List Number",
    "listBullet2": "List Bullet 2",
    "listNumber2": "List Number 2",
    "codeBlock": "Preformatted Text",
    "blockQuote": "Quotations",
    "codeSpan": "Source Text",
    "codeFontName": "Liberation Mono"
  },
  "contentAreas": [
    {
      "content": "**Firma Beispiel GmbH**\nFrau Anna Müller\nMusterstraße 42\n*12345 Berlin*",
      "x": 25,
      "y": 50,
      "width": 80,
      "height": 35,
      "fontName": "OpenSans",
      "customFonts": {
        "regular": "AAEAAAARAQ...",
        "bold": "AAEAAAARAQ..."
      },
      "fontSize": 10,
      "lineHeight": 1.4,
      "color": "#333333",
      "alignment": "LEFT",
      "barcode": {
        "format": "EAN13",
        "width": 60,
        "height": 25
      },
      "imageBase64": "iVBORw0KGgoAAAANS..."
    }
  ],
  "stationery": {
    "pdf": "JVBERi0xLjQK...",
    "firstPagePdf": "JVBERi0xLjQK..."
  },
  "invoice": {
    "number": "RE-2026-001",
    "date": "2026-03-25",
    "dueDate": "2026-04-25",
    "currency": "EUR",
    "seller": {
      "name": "Muster GmbH",
      "street": "Musterstraße 1",
      "city": "Berlin",
      "country": "DE",
      "vatId": "DE123456789",
      "email": "info@muster.de",
      "phone": "+49 30 1234567"
    },
    "buyer": {
      "name": "Muster GmbH",
      "street": "Musterstraße 1",
      "city": "Berlin",
      "country": "DE",
      "vatId": "DE123456789",
      "email": "info@muster.de",
      "phone": "+49 30 1234567"
    },
    "items": [
      {
        "description": "Software Development",
        "quantity": 10,
        "unit": "HUR",
        "unitPrice": 150,
        "vatRate": 19
      }
    ],
    "paymentTerms": "Net 30 days",
    "bankAccount": {
      "iban": "DE89370400440532013000",
      "bic": "COBADEFFXXX",
      "accountHolder": "Muster GmbH"
    },
    "referenceNumber": "04011000-12345-67",
    "buyerReference": "04011000-12345-67",
    "sellerTaxNumber": "27/123/12345"
  },
  "callbackUrl": "https://example.com/api/webhook/docgen",
  "callbackSecret": "my-webhook-secret-123"
}

Response

Job accepted

Changes

No recorded changes to this operation across all 1 revision of this API.