API Documentation

Authentication

All API requests require authentication using an API key. Include your API key in the Authorization header:

Authorization: Bearer pm_live_xxxxxxxxxxxxxxxxxxxx

Or use the X-API-Key header:

X-API-Key: pm_live_xxxxxxxxxxxxxxxxxxxx

API keys starting with pm_test_ are for testing. Use pm_live_ keys in production.

Quick Start

Generate your first PDF in 3 steps:

1. Create a Template

curl -X POST https://pdfmodule.com/api/v1/templates \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Simple Invoice",
    "body_html": "<h1>Invoice #{{invoice.number}}</h1><p>Total: {{formatCurrency total \"USD\"}}</p>"
  }'

2. Render a PDF

curl -X POST https://pdfmodule.com/api/v1/render \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "simple-invoice",
    "data": {
      "invoice": {"number": "INV-001"},
      "total": 299.99
    }
  }'

3. Download the PDF

curl https://pdfmodule.com/api/v1/documents/UUID/download \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o invoice.pdf

Error Handling

The API returns standard HTTP status codes:

Error responses include a JSON body:

{
  "error": "Template not found",
  "errors": {
    "field_name": ["Error message"]
  }
}

Render PDF

Request Body

Example with Chromium Engine

curl -X POST https://pdfmodule.com/api/v1/render \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "chart-report",
    "data": {"values": [10, 20, 30]},
    "engine": "chromium"
  }'

Response

Returns the PDF file directly with Content-Type: application/pdf

Response headers include:

Validate

Request Body

Response

{
  "valid": true,
  "errors": [],
  "warnings": [
    {
      "type": "large_table",
      "severity": "medium",
      "field": "items",
      "message": "Table 'items' has 75 rows - may split across pages"
    }
  ]
}

Rendering Engines

PDFModule supports multiple rendering engines to handle different template requirements. Choose the right engine based on your CSS complexity and performance needs.

Available Engines

When to Use Each Engine

Response

{
  "default_engine": "wkhtmltopdf",
  "available_engines": [
    {
      "name": "wkhtmltopdf",
      "version": {"engine": "wkhtmltopdf", "wkhtmltopdf": "0.12.6"},
      "features": ["basic-css", "tables", "images", "headers-footers", "page-numbers"],
      "limitations": ["flexbox", "css-grid", "canvas", "modern-javascript"]
    },
    {
      "name": "chromium",
      "version": {"engine": "chromium", "node_version": "v20.0.0"},
      "features": ["flexbox", "css-grid", "canvas", "chart-js", "modern-css", "es6-javascript"],
      "limitations": []
    }
  ]
}

Request Body

Response

{
  "template": "dashboard-report",
  "version": 3,
  "current_engine": null,
  "analysis": {
    "detected_features": ["flexbox", "css-grid", "canvas"],
    "recommended_engine": "chromium",
    "reason": "Modern CSS features detected: flexbox, css-grid, canvas"
  }
}

Setting Default Engine per Template

You can set a default rendering engine for each template. This engine will be used unless overridden in the render request.

curl -X PUT https://pdfmodule.com/api/v1/templates/my-template \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "render_engine": "chromium"
  }'

Templates

Create Template Request

Documents

Query Parameters

Document Storage & Retention

Generated PDF documents are stored temporarily and automatically deleted after a retention period based on your plan. This is designed for GDPR compliance.

Retention Periods by Plan

You can configure a shorter retention period via the API or dashboard settings. Documents are automatically deleted after their expiration date.

Response

{
  "plan": "production",
  "storage": {
    "retention_days": 30,
    "max_retention_days": 30,
    "custom_retention": false
  },
  "limits": {
    "pdf_limit": 5000,
    "template_limit": 50,
    "api_key_limit": 5
  }
}

Request Body

Example Request

curl -X PUT https://pdfmodule.com/api/v1/account/settings \
  -H "Authorization: Bearer pm_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"retention_days": 14}'

Document Expiration

When you download or retrieve a document, the response includes an expires_at timestamp. After this date:

• The document is no longer available for download
• Download requests return HTTP 410 (Gone)
• The PDF file is permanently deleted from storage

Account

Response includes storage info

{
  "daily": [...],
  "monthly": {...},
  "limits": {
    "pdf_limit": 5000,
    "pdfs_used": 150,
    "remaining": 4850
  },
  "storage": {
    "retention_days": 30,
    "max_retention_days": 30
  }
}

PDF Preflight - Overview

The Preflight API allows you to analyze and fix PDF files for print production. It checks for common issues like missing bleed, non-embedded fonts, RGB colors, and low-resolution images.

Available Checks

Available Fixes

Check PDF

Request (multipart/form-data)

Example: Basic Preflight Check

curl -X POST https://pdfmodule.com/api/v1/preflight \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@document.pdf"

Example: Check Specific Categories

curl -X POST https://pdfmodule.com/api/v1/preflight \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@document.pdf" \
  -F "checks=geometry,colors,fonts"

Example: Check with Profile

curl -X POST https://pdfmodule.com/api/v1/preflight \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@document.pdf" \
  -F "profile=print_strict"

Example: Check with Custom Config

curl -X POST https://pdfmodule.com/api/v1/preflight \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@document.pdf" \
  -F 'config={"bleed_required_mm": 5, "min_resolution_ppi": 300}'

Example: Check PDF from URL

curl -X POST https://pdfmodule.com/api/v1/preflight \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "pdf_url=https://example.com/document.pdf"

Response

{
  "version": "1.0",
  "timestamp": "2024-01-15T10:30:00Z",
  "file": {
    "name": "document.pdf",
    "size_bytes": 1451136,
    "page_count": 4,
    "pdf_version": "1.4"
  },
  "summary": {
    "status": "FAIL",
    "total_issues": 12,
    "fail_count": 4,
    "warn_count": 6,
    "info_count": 2,
    "checks_run": ["geometry", "fonts", "colors", "images", "transparency"]
  },
  "checks": {
    "geometry": {
      "pages": [
        {
          "number": 1,
          "dimensions_mm": {"width": 210.0, "height": 297.0},
          "bleed_mm": {"top": 0, "right": 0, "bottom": 0, "left": 0},
          "boxes": {
            "mediabox": [0, 0, 595.28, 841.89],
            "trimbox": [0, 0, 595.28, 841.89],
            "bleedbox": [0, 0, 595.28, 841.89]
          }
        }
      ],
      "issues": [
        {
          "id": "GEOM_BLEED_INSUFFICIENT",
          "severity": "FAIL",
          "page": 1,
          "message": "Page 1: Insufficient bleed on all edges (0mm, need 3mm)",
          "details": {"found_mm": 0, "required_mm": 3}
        }
      ]
    },
    "fonts": {
      "fonts": {
        "Helvetica": {
          "embedded": false,
          "subset": false,
          "type": "Type1"
        }
      },
      "issues": [
        {
          "id": "FONT_NOT_EMBEDDED",
          "severity": "FAIL",
          "message": "Font \"Helvetica\" is not embedded",
          "details": {"font": "Helvetica", "recommendation": "Embed the font or convert to outlines"}
        }
      ]
    },
    "colors": {
      "color_spaces": ["DeviceRGB", "DeviceCMYK"],
      "has_rgb": true,
      "has_cmyk": true,
      "has_spot": false,
      "issues": [
        {
          "id": "COLOR_RGB_FOUND",
          "severity": "WARN",
          "message": "RGB colors found - may need conversion for print"
        }
      ]
    },
    "images": {
      "images": [
        {
          "page": 1,
          "width": 1200,
          "height": 800,
          "x_ppi": 150,
          "y_ppi": 150,
          "color": "rgb"
        }
      ],
      "issues": [
        {
          "id": "IMAGE_LOW_RES",
          "severity": "WARN",
          "page": 1,
          "message": "Image has low resolution (150 PPI, recommended 300+)"
        }
      ]
    }
  }
}

Issue Severity Levels

Fix PDF

Request (multipart/form-data)

Bleed Options

Page Box Options (set_boxes fix)

Crop Marks Options (crop_marks fix)

Resize Options (resize fix)

Color Options (convert_cmyk, convert_rgb, convert_gray fixes)

Optimization Options (optimize fix)

Cut Contour Options (cut_contour fix)

Response

Returns the fixed PDF file directly with Content-Type: application/pdf

Example: Add 3mm Bleed

curl -X POST https://pdfmodule.com/api/v1/preflight/fix \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@document.pdf" \
  -F "fixes=smart_bleed" \
  -F "bleed_mm=3" \
  -o fixed-document.pdf

Example: Convert to CMYK

curl -X POST https://pdfmodule.com/api/v1/preflight/fix \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@document.pdf" \
  -F "fixes=convert_cmyk" \
  -F "icc_profile=fogra39" \
  -o cmyk-document.pdf

Example: Add Crop Marks with Bleed

curl -X POST https://pdfmodule.com/api/v1/preflight/fix \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@document.pdf" \
  -F "fixes=smart_bleed,crop_marks" \
  -F "bleed_mm=3" \
  -F "add_trim_marks=true" \
  -F "add_registration=true" \
  -F "add_color_bars=false" \
  -o print-ready.pdf

Example: Resize to A4 and Convert to CMYK

curl -X POST https://pdfmodule.com/api/v1/preflight/fix \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@document.pdf" \
  -F "fixes=resize,convert_cmyk" \
  -F "target_size=A4" \
  -F "fit_mode=fit" \
  -o resized-cmyk.pdf

Example: Add Cut Contour (Die Line)

curl -X POST https://pdfmodule.com/api/v1/preflight/fix \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@sticker.pdf" \
  -F "fixes=cut_contour" \
  -F "cut_source=content" \
  -F "cut_inset_mm=0" \
  -F "cut_spot_name=CutContour" \
  -o sticker-with-dieline.pdf

Example: Rounded Rectangle Cut Contour

curl -X POST https://pdfmodule.com/api/v1/preflight/fix \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@business-card.pdf" \
  -F "fixes=cut_contour" \
  -F "cut_source=shape" \
  -F "cut_shape=rounded" \
  -F "cut_corner_radius_mm=3" \
  -o card-with-dieline.pdf

Example: Full Print Preparation

curl -X POST https://pdfmodule.com/api/v1/preflight/fix \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@document.pdf" \
  -F "fixes=smart_bleed,convert_cmyk,flatten,crop_marks" \
  -F "bleed_mm=3" \
  -F "icc_profile=fogra39" \
  -F "add_trim_marks=true" \
  -F "add_registration=true" \
  -o print-ready.pdf

Example: Optimize for Web

curl -X POST https://pdfmodule.com/api/v1/preflight/fix \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@large-document.pdf" \
  -F "fixes=convert_rgb,optimize" \
  -F "optimize_preset=screen" \
  -o web-optimized.pdf

Preflight Profiles

Profiles define a set of rules and thresholds for preflight checks. Use system profiles or create your own custom profiles.

System Profiles

Example: List Profiles

curl -X GET https://pdfmodule.com/api/v1/preflight/profiles \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "profiles": [
    {
      "slug": "print_standard",
      "name": "Print Standard",
      "description": "Standard commercial print requirements",
      "is_system": true,
      "bleed_mm": 3.0,
      "bleed_required": true,
      "min_resolution_ppi": 300,
      "color_mode": "cmyk_preferred",
      "fonts_embedded_required": true
    },
    {
      "slug": "my-custom-profile",
      "name": "My Custom Profile",
      "is_system": false,
      "bleed_mm": 5.0,
      "min_resolution_ppi": 350
    }
  ]
}

Example: Get Profile

curl -X GET https://pdfmodule.com/api/v1/preflight/profiles/print_standard \
  -H "Authorization: Bearer YOUR_API_KEY"

Request Body

Example: Create Custom Profile

curl -X POST https://pdfmodule.com/api/v1/preflight/profiles \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Magazine Print",
    "description": "Requirements for magazine printing",
    "bleed_mm": 5.0,
    "bleed_required": true,
    "min_resolution_ppi": 300,
    "warn_resolution_ppi": 250,
    "color_mode": "cmyk_required",
    "allow_rgb": false,
    "allow_spot_colors": true,
    "fonts_embedded_required": true,
    "allow_transparency": false
  }'

Example: Update Profile

curl -X PUT https://pdfmodule.com/api/v1/preflight/profiles/magazine-print \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "bleed_mm": 4.0,
    "min_resolution_ppi": 350
  }'

Example: Delete Profile

curl -X DELETE https://pdfmodule.com/api/v1/preflight/profiles/magazine-print \
  -H "Authorization: Bearer YOUR_API_KEY"

Example: Health Check

curl -X GET https://pdfmodule.com/api/v1/preflight/health \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "status": "healthy",
  "service": {
    "status": "ok"
  }
}

Imposition

The Imposition API arranges print-ready PDFs on press sheets for efficient printing. It supports multiple layout types, automatic optimization, crop marks, and product templates.

Layout Types

Generate Imposed PDF

Parameters

Example: Business Cards

curl -X POST https://pdfmodule.com/api/v1/impose \
  -H "Authorization: Bearer pm_live_xxxx" \
  -F file=@business-card.pdf \
  -F layout=step_repeat \
  -F sheet_size=SRA3 \
  -F bleed_mm=3 \
  -F marks=crop,registration \
  -o imposed.pdf

Example: Using Template

curl -X POST https://pdfmodule.com/api/v1/impose \
  -H "Authorization: Bearer pm_live_xxxx" \
  -F file=@card.pdf \
  -F template=business_cards \
  -o imposed.pdf

Example: A5 Booklet

curl -X POST https://pdfmodule.com/api/v1/impose \
  -H "Authorization: Bearer pm_live_xxxx" \
  -F file=@booklet-pages.pdf \
  -F layout=booklet \
  -F sheet_size=SRA3 \
  -F bleed_mm=3 \
  -F creep_mm=0.5 \
  -F marks=crop,registration,fold \
  -o booklet-imposed.pdf

Preview Layout

Accepts the same parameters as /api/v1/impose. Returns JSON with layout details, item positions, waste percentage, and alternative sheet sizes.

curl -X POST https://pdfmodule.com/api/v1/impose/preview \
  -H "Authorization: Bearer pm_live_xxxx" \
  -F file=@flyer.pdf \
  -F layout=step_repeat \
  -F sheet_size=SRA3 \
  -F auto_optimize=true

Response

{
  "success": true,
  "input": {
    "trim_width_mm": 148.0,
    "trim_height_mm": 210.0,
    "bleed_mm": {"top": 3, "right": 3, "bottom": 3, "left": 3},
    "page_count": 1
  },
  "layout": {
    "type": "step_repeat",
    "sheet_size": "SRA3",
    "sheet_width_mm": 320.0,
    "sheet_height_mm": 450.0,
    "rows": 2,
    "cols": 2,
    "items_per_sheet": 4,
    "rotation_deg": 0,
    "total_sheets": 1
  },
  "waste": {
    "per_sheet_pct": 13.8
  },
  "alternatives": [
    {"sheet": "SRA2", "items_per_sheet": 4, "waste_pct": 56.8, "rotation": 0},
    {"sheet": "70x100", "items_per_sheet": 12, "waste_pct": 47.0, "rotation": 0}
  ]
}

Product Templates

Available Templates

List Layouts

Sheet Sizes

Press Sheet Sizes

Custom sheet sizes can be specified using sheet_width_mm and sheet_height_mm parameters.

Large Format Nesting

Wide-format, signage, packaging, and industrial print workflows. Includes roll substrates, flatbed nesting, tiling/splitting, contour-aware nesting, bleed sharing, and white ink layer support.

New Layout Types

Large Format Parameters

Roll Substrate

curl -X POST https://pdfmodule.com/api/v1/impose \
  -H "Authorization: Bearer pm_live_xxxx" \
  -F file=@stickers.pdf \
  -F layout=roll \
  -F substrate_type=roll \
  -F roll_width_mm=1524 \
  -F copies=50 \
  -o roll-output.pdf

Flatbed Nesting

curl -X POST https://pdfmodule.com/api/v1/impose \
  -H "Authorization: Bearer pm_live_xxxx" \
  -F file=@signs.pdf \
  -F layout=flatbed \
  -F substrate_type=flatbed \
  -F bed_width_mm=1220 \
  -F bed_height_mm=2440 \
  -F rotation_steps=4 \
  -o flatbed-output.pdf

Tiling / Splitting

curl -X POST https://pdfmodule.com/api/v1/impose \
  -H "Authorization: Bearer pm_live_xxxx" \
  -F file=@mural.pdf \
  -F layout=tiling \
  -F sheet_size=A3 \
  -F tile_overlap_mm=15 \
  -F tile_order=lrtb \
  -o tiled-output.pdf

White Ink Layer

curl -X POST https://pdfmodule.com/api/v1/impose \
  -H "Authorization: Bearer pm_live_xxxx" \
  -F file=@acrylic-sign.pdf \
  -F layout=flatbed \
  -F substrate_type=flatbed \
  -F bed_width_mm=2050 \
  -F bed_height_mm=3050 \
  -F white_ink_mode=auto \
  -o white-ink-output.pdf

Reference Endpoints

Large Format Templates

Zünd (ZUND) Cutter Marks

For workflows ending on a Zünd digital cutter with camera registration (ZCC), add the zund token to marks. The imposer draws filled 100% K circles that the cutter's camera locates to align its cuts to the artwork.

• Diameter (zund_diameter_mm, default 5) — Zünd typically recommends 3–6 mm; 5 mm is a safe default across bed sizes.
• Offset (zund_offset_mm, default 10) — distance from the reference edge. Leave clear white space around each mark for reliable detection.
• Placement (zund_placement) — sheet (4 marks at the sheet corners, for signage/banners/flatbed nests), item (4 marks around each placed item, for contour-cut stickers/labels), or both.

Circles are drawn with CMYK 0 0 0 1. Do not re-process the output through color conversion that might recompose the K channel, or the cutter's camera may miss the marks.

Sheet-level (flatbed signage)

curl -X POST https://pdfmodule.com/api/v1/impose \
  -H "Authorization: Bearer pm_live_xxxx" \
  -F file=@sign.pdf \
  -F layout=flatbed \
  -F substrate_type=flatbed \
  -F bed_width_mm=3200 \
  -F bed_height_mm=2000 \
  -F marks=crop,zund \
  -F zund_diameter_mm=5 \
  -F zund_offset_mm=10 \
  -F zund_placement=sheet \
  -o sign-zund.pdf

Per-item (contour-cut stickers)

curl -X POST https://pdfmodule.com/api/v1/impose \
  -H "Authorization: Bearer pm_live_xxxx" \
  -F file=@sticker.pdf \
  -F layout=flatbed \
  -F substrate_type=flatbed \
  -F bed_width_mm=1220 \
  -F bed_height_mm=2440 \
  -F nesting_algorithm=maxrect \
  -F copies=40 \
  -F marks=crop,zund \
  -F zund_placement=item \
  -o stickers-zund.pdf

Page Layout & Margins

Understanding how margins, headers, and footers work together is essential for creating well-formatted PDFs. This section explains exactly how your content is positioned on the page.

How the Page is Structured

Every PDF page has distinct areas. Here's a visual representation:

┌─────────────────────────────────────────────────┐
│                   margin_top                    │
│  ┌───────────────────────────────────────────┐  │
│  │              HEADER AREA                  │  │
│  │   (header_html renders here)              │  │
│  └───────────────────────────────────────────┘  │
│                                                 │
│  ┌───────────────────────────────────────────┐  │
│  │                                           │  │
│  │                                           │  │
│m │           BODY CONTENT AREA               │m │
│a │                                           │a │
│r │        (body_html renders here)           │r │
│g │                                           │g │
│i │                                           │i │
│n │                                           │n │
│_ │                                           │_ │
│l │                                           │r │
│e │                                           │i │
│f │                                           │g │
│t │                                           │h │
│  │                                           │t │
│  └───────────────────────────────────────────┘  │
│                                                 │
│  ┌───────────────────────────────────────────┐  │
│  │              FOOTER AREA                  │  │
│  │   (footer_html renders here)              │  │
│  └───────────────────────────────────────────┘  │
│                  margin_bottom                  │
└─────────────────────────────────────────────────┘

Margin Parameters

Recommended Margin Values

Common Mistake: Overlapping Content

The most common issue is content overlapping with headers or footers. This happens when margins are too small:

{
  "header_html": "<div>My Header</div>",
  "footer_html": "<div>Page {{page}}</div>",
  "margin_top": 10,
  "margin_bottom": 10
}

{
  "header_html": "<div>My Header</div>",
  "footer_html": "<div>Page {{page}}</div>",
  "margin_top": 25,
  "margin_bottom": 25
}

Complete Example

curl -X POST https://pdfmodule.com/api/v1/templates \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Professional Report",
    "body_html": "<h1>{{title}}</h1><p>{{content}}</p>",
    "header_html": "<div style=\"font-size: 10px; color: #666; border-bottom: 1px solid #ddd; padding-bottom: 5px;\">{{company}} - Confidential</div>",
    "footer_html": "<div style=\"font-size: 9px; color: #999; text-align: center;\">Page {{page}} of {{pages}}</div>",
    "page_size": "A4",
    "orientation": "portrait",
    "margin_top": 25,
    "margin_bottom": 20,
    "margin_left": 15,
    "margin_right": 15
  }'

Page Sizes

Headers & Footers

Headers appear at the top of every page; footers appear at the bottom. They're perfect for page numbers, company logos, document titles, and confidentiality notices.

Quick Start

Add a simple footer with page numbers:

{
  "footer_html": "<div style=\"text-align: center; font-size: 10px;\">Page {{page}} of {{pages}}</div>",
  "margin_bottom": 20
}

Available Placeholders

Alignment Shortcuts

Use these directives at the start of your header/footer for quick alignment:

// Right-aligned page numbers
"footer_html": "{{right}}Page {{page}} of {{pages}}"

// Centered company name
"header_html": "{{center}}ACME Corporation"

Header/Footer Styling Examples

Simple Centered Footer

"footer_html": "<div style=\"text-align: center; font-size: 10px; color: #666;\">Page {{page}} of {{pages}}</div>"

Header with Border

"header_html": "<div style=\"font-size: 11px; color: #333; border-bottom: 1px solid #ddd; padding-bottom: 5px;\">Document Title</div>"

Left + Right Content (Two Columns)

"footer_html": "<div style=\"display: flex; justify-content: space-between; font-size: 9px; color: #666;\"><span>Confidential</span><span>Page {{page}} of {{pages}}</span></div>"

Header with Logo Placeholder

"header_html": "<div style=\"display: flex; justify-content: space-between; align-items: center;\"><span style=\"font-weight: bold;\">{{company}}</span><span style=\"font-size: 10px; color: #666;\">{{formatDate date 'M j, Y'}}</span></div>"

Automatic Margin Alignment

Headers and footers automatically inherit margin_left and margin_right from your page settings. This ensures your header/footer text aligns perfectly with your body content.

Page with margin_left: 15mm and margin_right: 15mm:

│←15mm→│                                    │←15mm→│
       ┌────────────────────────────────────┐
       │ Header text aligns here            │  ← header
       ├────────────────────────────────────┤
       │ Body content starts here           │  ← body
       │ ...                                │
       ├────────────────────────────────────┤
       │ Footer text aligns here            │  ← footer
       └────────────────────────────────────┘

Complete Example with Header & Footer

curl -X POST https://pdfmodule.com/api/v1/templates \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Invoice",
    "body_html": "<h1>Invoice #{{invoice.number}}</h1><p>Customer: {{customer.name}}</p>",
    "header_html": "<div style=\"display: flex; justify-content: space-between; font-size: 10px; color: #666; border-bottom: 1px solid #eee; padding-bottom: 5px;\"><span>{{company}}</span><span>Invoice #{{invoice.number}}</span></div>",
    "footer_html": "<div style=\"display: flex; justify-content: space-between; font-size: 9px; color: #999;\"><span>Generated {{currentDate \"M j, Y\"}}</span><span>Page {{page}} of {{pages}}</span></div>",
    "margin_top": 25,
    "margin_bottom": 20,
    "margin_left": 15,
    "margin_right": 15
  }'

Troubleshooting

Template Syntax

Templates use a Handlebars-like syntax for dynamic content:

Variables

<p>Hello, {{customer.name}}</p>
<p>Order #{{order.id}}</p>

Loops

{{#each items}}
  <tr>
    <td>{{description}}</td>
    <td>{{quantity}}</td>
    <td>{{formatCurrency unit_price "USD"}}</td>
  </tr>
{{/each}}

Conditionals

{{#if discount}}
  <p>Discount: {{formatCurrency discount "USD"}}</p>
{{/if}}

{{#if premium}}
  <p>Premium member</p>
{{else}}
  <p>Standard member</p>
{{/if}}

Loop Variables

Built-in Helpers

Page Breaks

Control where page breaks occur in your PDF documents using the page break helpers. This is essential for multi-page reports, sections, or any document where you want content to start on a new page.

Available Helpers

Basic Example

Split your document into separate pages:

<h1>Section 1: Introduction</h1>
<p>Content for the first section...</p>

{{pageBreak}}

<h1>Section 2: Analysis</h1>
<p>This content will start on a new page...</p>

{{pageBreak}}

<h1>Section 3: Conclusion</h1>
<p>This content will also start on a new page...</p>

Page Breaks in Loops

Add page breaks between items in a loop, but not after the last item:

{{#each sections}}
  <div class="section">
    <h1>{{title}}</h1>
    <p>{{content}}</p>
  </div>
  {{#unless @last}}{{pageBreak}}{{/unless}}
{{/each}}

Conditional Page Breaks

Only add a page break when a condition is met:

{{#if appendix}}
  {{pageBreak}}
  <h1>Appendix</h1>
  <p>{{appendix}}</p>
{{/if}}

Multi-Part Reports

Example of a structured report with page breaks:

<!-- Cover Page -->
<div class="cover-page">
  <h1>{{report.title}}</h1>
  <p>Prepared for: {{client.name}}</p>
  <p>Date: {{formatDate report.date "F j, Y"}}</p>
</div>

{{pageBreak}}

<!-- Executive Summary -->
<h2>Executive Summary</h2>
<p>{{report.summary}}</p>

{{pageBreak}}

<!-- Detailed Findings -->
{{#each report.findings}}
  <h2>{{title}}</h2>
  <p>{{description}}</p>
  {{#unless @last}}{{pageBreak}}{{/unless}}
{{/each}}

{{pageBreak}}

<!-- Recommendations -->
<h2>Recommendations</h2>
{{#each report.recommendations}}
  <p>{{@index}}. {{this}}</p>
{{/each}}

CSS Alternative

You can also use CSS for page break control in your styles_css:

/* Force page break after an element */
.section {
  page-break-after: always;
}

/* Force page break before an element */
.new-chapter {
  page-break-before: always;
}

/* Prevent page break inside an element */
.keep-together {
  page-break-inside: avoid;
}

CSS Support by Engine

Different rendering engines support different CSS features. Use this reference to choose the right engine for your template.

Layout

Visual

Content

Example: Chart.js with Chromium

To render Chart.js charts, use the chromium engine:

<!-- Template body_html -->
<canvas id="myChart" width="400" height="200"></canvas>
<script src="https://cdn.jsdelivr.net/npm/chart.js"></script>
<script>
  new Chart(document.getElementById('myChart'), {
    type: 'bar',
    data: {
      labels: {{json labels}},
      datasets: [{
        label: 'Sales',
        data: {{json values}},
        backgroundColor: '#3b82f6'
      }]
    }
  });
</script>

// API request
{
  "template": "sales-chart",
  "data": {
    "labels": ["Jan", "Feb", "Mar"],
    "values": [12, 19, 8]
  },
  "engine": "chromium"
}

Performance Comparison

Times are approximate and vary based on content complexity.

Advanced PDF Template

The Advanced PDF template is a powerful, flexible template that uses the Chromium rendering engine. It's designed to handle complex layouts that aren't possible with basic PDF generators.

Use Cases

The Advanced PDF template can be customized for many different applications:

Example: Dashboard Report

curl -X POST https://pdfmodule.com/api/v1/render \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "advanced-pdf",
    "engine": "chromium",
    "data": {
      "title": "Sales Dashboard",
      "subtitle": "Q4 2024 Performance Overview",
      "primary_color": "#3b82f6",
      "secondary_color": "#8b5cf6",
      "metrics": [
        {"value": "$1.2M", "label": "Revenue", "change": "+15%", "change_type": "positive"},
        {"value": "847", "label": "New Customers", "change": "+23%", "change_type": "positive"}
      ],
      "chart": {
        "title": "Monthly Sales",
        "type": "bar",
        "labels": ["Jan", "Feb", "Mar", "Apr"],
        "data": [45, 62, 78, 91]
      }
    }
  }'

Example: Assessment Report

{
  "template": "advanced-pdf",
  "engine": "chromium",
  "data": {
    "title": "Leadership Assessment",
    "subtitle": "Comprehensive skill evaluation for Jane Smith",
    "icon": "👤",
    "primary_color": "#10b981",
    "secondary_color": "#059669",
    "metrics": [
      {"value": "92", "label": "Overall Score"},
      {"value": "A+", "label": "Rating"},
      {"value": "Top 5%", "label": "Percentile"}
    ],
    "progress": {
      "title": "Competency Scores",
      "items": [
        {"label": "Communication", "value": 95},
        {"label": "Problem Solving", "value": 88},
        {"label": "Leadership", "value": 92},
        {"label": "Teamwork", "value": 85}
      ]
    },
    "chart": {
      "type": "radar",
      "title": "Skill Profile",
      "labels": ["Strategy", "Execution", "Innovation", "People", "Results"],
      "data": [90, 85, 78, 92, 88]
    }
  }
}

Example: Analytics Report

{
  "template": "advanced-pdf",
  "engine": "chromium",
  "data": {
    "title": "Website Analytics",
    "subtitle": "Traffic and conversion analysis for December 2024",
    "icon": "📈",
    "primary_color": "#f59e0b",
    "secondary_color": "#d97706",
    "metrics": [
      {"value": "124K", "label": "Visitors"},
      {"value": "3.2%", "label": "Conversion Rate"},
      {"value": "2:34", "label": "Avg. Session"},
      {"value": "42%", "label": "Bounce Rate"}
    ],
    "chart": {
      "type": "line",
      "title": "Daily Traffic",
      "labels": ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"],
      "data": [4200, 4800, 5100, 4900, 5500, 3200, 2800],
      "fill": true
    },
    "table": {
      "title": "Top Pages",
      "headers": ["Page", "Views", "Bounce Rate", "Conversions"],
      "rows": [
        ["/pricing", "12,450", "28%", "892"],
        ["/features", "9,823", "35%", "456"],
        ["/demo", "7,234", "22%", "678"]
      ]
    }
  }
}

Customization Options

Chart Types

The Advanced PDF template supports all Chart.js chart types:

• bar - Compare values across categories
• line - Show trends over time
• pie / doughnut - Show proportions of a whole
• radar - Compare multiple variables (great for assessments)
• polarArea - Similar to pie but with equal angles