Template Mode Overview

Template Mode lets you create documents from Word templates by replacing placeholders with your data. Upload a template once, then generate unlimited customized documents.

Complete Invoice Example

See how all template features work together in a real invoice:

Template with Placeholders

Generated Invoice

Template Configuration

How to create the template (click to expand)

First, create the Word template document using the Document Generation API. Use placeholders like {{variableName}} where you want dynamic content.

Step 1: Create template document with placeholders

{
  "document": {
    "type": "docx",
    "filename": "invoice-template",
    "size": "A4",
    "orientation": "portrait"
  },
  "defaults": {
    "fontFamily": "Arial",
    "fontSize": 10,
    "footer": {
      "center": "Page {{pageNumber}} of {{totalPages}}"
    }
  },
  "sections": [
    {
      "type": "flow",
      "content": [
        {
          "type": "text",
          "text": "{{companyLogo}}"
        },
        {
          "type": "h1",
          "text": "INVOICE"
        },
        {
          "type": "text",
          "text": "**{{companyName}}**"
        },
        {
          "type": "text",
          "text": "{{companyAddress}}"
        },
        {
          "type": "text",
          "text": "Invoice Number: {{invoiceNumber}}"
        },
        {
          "type": "text",
          "text": "Invoice Date: {{invoiceDate}}"
        },
        {
          "type": "h2",
          "text": "Services"
        },
        {
          "type": "table",
          "headers": ["Pos.", "Description", "Qty", "Unit Price", "Total"],
          "rows": [
            ["{{items.position}}", "{{items.description}}", "{{items.quantity}}", "{{items.unitPrice}}", "{{items.total}}"]
          ]
        },
        {
          "type": "text",
          "text": "**Subtotal:** {{subtotal}}",
          "align": "right"
        },
        {
          "type": "text",
          "text": "**Tax {{taxRate}}:** {{taxAmount}}",
          "align": "right"
        },
        {
          "type": "text",
          "text": "**Total:** {{total}}",
          "align": "right",
          "fontWeight": "bold"
        },
        {
          "type": "h2",
          "text": "Service Description"
        },
        {
          "type": "text",
          "text": "{{services}}"
        }
      ]
    }
  ]
}

Step 2: Generate the template document

curl -X POST 'https://api.json2doc.com/v1/jobs' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d @invoice-template.json

Step 3: Download the generated template

curl -H "x-api-key: YOUR_API_KEY" \
  -o invoice-template.docx \
  https://api.json2doc.com/v1/jobs/{jobId}/download

Step 4: Upload as reusable template

curl -X POST 'https://api.json2doc.com/v1/templates/upload' \
  -H 'x-api-key: YOUR_API_KEY' \
  -F 'file=@invoice-template.docx' \
  -F 'name="Invoice Template"'

Response:

{
  "success": true,
  "data": {
    "id": "invoice-template-2024",
    "name": "Invoice Template",
    "variables": ["companyLogo", "companyName", "items", "services"]
  }
}

Generate Documents

Once your template is uploaded, generate documents by sending variable data:

{
  "templateId": "invoice-template-2024",
  "variables": {
    "companyLogo": {
      "type": "image",
      "src": "/images/company-logo.png",
      "width": 50
    },
    "companyName": "TechSolutions AG",
    "companyAddress": "123 Business Street",
    "invoiceNumber": "INV-2024-001",
    "invoiceDate": "November 15, 2024",
    "customerName": "Client Company GmbH",
    "items": {
      "type": "table",
      "data": [
        {
          "position": "1",
          "description": "Website Development",
          "quantity": "1",
          "unitPrice": "2,500.00 €",
          "total": "2,500.00 €"
        },
        {
          "position": "2",
          "description": "SEO Optimization",
          "quantity": "10",
          "unitPrice": "150.00 €",
          "total": "1,500.00 €"
        }
      ]
    },
    "services": {
      "type": "list",
      "items": [
        "- Responsive web design for all devices",
        "- SEO-optimized content structure",
        "- Performance optimization",
        "- Security updates and monitoring"
      ]
    },
    "subtotal": "4,000.00 €",
    "taxRate": "19%",
    "taxAmount": "760.00 €",
    "total": "4,760.00 €"
  },
  "output": {
    "filename": "invoice-2024-001",
    "type": "pdf"
  }
}

Variable Types

Template Mode supports five variable types: text, images, QR codes, tables, and lists. Each type has specific properties and use cases.

Automatic Type Detection (NEW ✨)

When you upload a DOCX template, json2doc scans all placeholders like {{variable}} and tries to infer example metadata for the Template Playground. This inference is strict and only recognizes non-string types when you use the prefixes shown below.

Placeholder in DOCX	JSON variables payload (snippet)	Type	Explanation
`{{companyName}}`	`"companyName": "TechSolutions AG"`	Text	No prefix → treated as simple text variable.
`{{ image.companyLogo }}`	`"companyLogo": { "type": "image", "src": "/images/company-logo.png" }`	Image	`image.` prefix → inspector infers an image variable `companyLogo`.
`{{ list.services }}`	`"services": { "type": "list", "items": ["Item 1", "Item 2"] }`	List	`list.` prefix → inspector infers a list variable `services`.
`{{ qr_url.websiteQR }}`	`"websiteQR": { "type": "qrcode", "qrType": "url", "data": { "url": "https://example.com" } }`	QR code (URL)	`qr_url.` prefix → URL QR code.
`{{ qr_wifi.wifiQR }}`	`"wifiQR": { "type": "qrcode", "qrType": "wifi", "data": { "ssid": "Office" } }`	QR code (WiFi)	`qr_wifi.` prefix → WiFi QR code.
`{{ qr_vcard.contactQR }}`	`"contactQR": { "type": "qrcode", "qrType": "vcard", "data": { "firstName": "John" } }`	QR code (vCard)	`qr_vcard.` prefix → vCard/contact QR code.
`{{ items.position }}`	`"items": { "type": "table", "data": [{ "position": "1", "description": "Row 1" }] }`	Table	Dot-notation without typed prefix (`items.*`) → dynamic table variable `items`.
`{{ table.items.position }}`	`"items": { "type": "table", "data": [{ "position": "1", "description": "Row 1" }] }`	Table	`table.` + base name (`table.items.`) is treated the same as `items.` and maps to the table variable `items`.

note

These naming rules affect only the automatic metadata generation when uploading templates. At runtime you can still send any valid JSON that matches the template schema (e.g. you may manually send {"companyLogo": {"type": "image", ...}} even if the placeholder is just {{companyLogo}}), but the inspector will treat such plain names as text and not prefill image/list/QR/table examples for them.

All inferred variables and their example metadata (types, example data, etc.) are exposed via the Template API:

Upload a template and get inferred variables in the response: see Upload a new template
Fetch all variables and metadata for an existing template: see Get template details

1. Text Variables

Simple string replacement for any text content.

Properties:

Value: String (1-1000 characters)
Required: Yes

Usage in template:

{{companyName}}
{{invoiceNumber}}
{{total}}

JSON example:

{
  "companyName": "TechSolutions AG",
  "invoiceNumber": "INV-2024-001",
  "total": "4,760.00 €"
}

Formatting: Text variables preserve the formatting of the placeholder in your template:

Bold placeholder → Bold text
Italic placeholder → Italic text
Colored placeholder → Colored text

2. Image Variables

Insert images (logos, signatures, photos) with optional dimensions.

Properties:

type: "image" (required)
src: Image source (required)
- Local file path starting with / (e.g., /images/logo.png)
- Public HTTP/HTTPS URL (e.g., https://example.com/logo.png)
width: Width in pixels (optional, 10-2000)
height: Height in pixels (optional, 10-2000)
alt: Alternative text for accessibility (optional, max 200 chars)

Usage in template:

{{companyLogo}}

JSON example:

{
  "companyLogo": {
    "type": "image",
    "src": "/images/company-logo.png",
    "width": 150,
    "height": 60,
    "alt": "Company Logo"
  }
}

Image source options:

Upload via API (recommended):

curl -X POST 'https://api.json2doc.com/v1/files/upload' \
  -H 'x-api-key: YOUR_API_KEY' \
  -F 'file=@logo.png' \
  -F 'category=image'

Response:

{
  "success": true,
  "data": {
    "path": "/images/2024-11-02/user123/logo-abc123.png"
  }
}

Use the returned path as the src value.

Public URL: Provide any public HTTP/HTTPS URL. The system will download and process the image automatically.

Sizing:

If neither width nor height specified: Original size (max 4 inches)
If only width specified: Height scaled proportionally
If only height specified: Width scaled proportionally
If both specified: Exact dimensions (may distort)

3. QR Code Variables

Generate and insert QR codes dynamically for URLs, WiFi credentials, or contact cards (vCard).

Properties:

type: "qrcode" (required)
qrType: QR code type (required)
- "url": Website links, YouTube videos, etc.
- "wifi": WiFi network credentials
- "vcard": Contact information (business card)
data: QR code content (required, structure depends on qrType)
size: QR code size in pixels (optional, 50-1000, default: 200)
- Always 1:1 aspect ratio (square)
errorCorrection: Error correction level (optional, default: "M")
- "L": ~7% - Smallest code, lowest error tolerance
- "M": ~15% - Standard, balanced
- "Q": ~25% - Higher error tolerance
- "H": ~30% - Highest error tolerance, best for damaged codes

Usage in template:

{{websiteQR}}
{{wifiQR}}
{{contactQR}}

JSON examples:

URL QR Code:

{
  "websiteQR": {
    "type": "qrcode",
    "qrType": "url",
    "data": {
      "url": "https://example.com"
    },
    "size": 150,
    "errorCorrection": "M"
  }
}

WiFi QR Code:

{
  "wifiQR": {
    "type": "qrcode",
    "qrType": "wifi",
    "data": {
      "ssid": "Office-Network",
      "password": "SecurePassword123",
      "encryption": "WPA",
      "hidden": false
    },
    "size": 200,
    "errorCorrection": "H"
  }
}

vCard QR Code:

{
  "contactQR": {
    "type": "qrcode",
    "qrType": "vcard",
    "data": {
      "firstName": "John",
      "lastName": "Doe",
      "organization": "ACME Corporation",
      "phone": "+1 234 567 8900",
      "email": "john.doe@example.com",
      "url": "https://example.com"
    },
    "size": 250,
    "errorCorrection": "H"
  }
}

Data structure by QR type:

URL (qrType: "url"):
- url (required): Any valid URL (max 2000 chars)
WiFi (qrType: "wifi"):
- ssid (required): Network name (max 32 chars)
- password (optional): Network password (max 63 chars)
- encryption (optional): "WPA", "WEP", or "nopass" (default: "WPA")
- hidden (optional): Boolean, whether network is hidden (default: false)
vCard (qrType: "vcard"):
- firstName (optional): First name (max 100 chars)
- lastName (optional): Last name (max 100 chars)
- organization (optional): Company name (max 100 chars)
- phone (optional): Phone number (max 50 chars)
- email (optional): Email address (max 100 chars)
- url (optional): Website URL (max 200 chars)
- address (optional): Physical address (max 200 chars)
- note (optional): Additional notes (max 500 chars)

Use cases:

Business cards: Add contact QR code for easy phone import
Event invitations: Include location QR code (Google Maps URL)
Product packaging: Link to product information or videos
WiFi access: Share network credentials without typing
Marketing materials: Direct customers to websites or social media

Tips:

Use error correction level "H" for business cards (may get damaged)
Use error correction level "M" for digital displays
Size 150-200px works well for business cards
Size 250-300px recommended for posters and larger prints
Test QR codes with multiple scanner apps before printing

4. Table Variables

Populate tables dynamically with multiple rows of data.

Properties:

type: "table" (required)
data: Array of row objects (required, 1-100 items)
- Each object represents one table row
- Object keys must match template placeholders

Usage in template:

Create a table in Word with a template row:

| Pos. | Description | Quantity | Unit Price | Total |
|------|-------------|----------|------------|-------|
| {{items.position}} | {{items.description}} | {{items.quantity}} | {{items.unitPrice}} | {{items.total}} |

JSON example:

{
  "items": {
    "type": "table",
    "data": [
      {
        "position": "1",
        "description": "Website Development",
        "quantity": "1",
        "unitPrice": "2,500.00 €",
        "total": "2,500.00 €"
      },
      {
        "position": "2",
        "description": "SEO Optimization",
        "quantity": "10",
        "unitPrice": "150.00 €",
        "total": "1,500.00 €"
      }
    ]
  }
}

How it works:

The template row (with placeholders) is removed
For each object in data, a new row is created
Placeholders like {{items.property}} are replaced with values
Formatting from the template row is preserved

Formatting:

Cell alignment, borders, and colors are preserved
Each placeholder's formatting (bold, italic, etc.) is applied to its value

5. List Variables

Insert bullet or numbered lists from an array of strings.

Properties:

type: "list" (required)
items: Array of strings (required, 1-50 items)
- Each string becomes a list item
- Max 1000 characters per item

Usage in template:

Services included:
{{services}}

JSON example:

{
  "services": {
    "type": "list",
    "items": [
      "Responsive web design for all devices",
      "Custom CMS integration",
      "SEO-optimized content structure",
      "Performance optimization"
    ]
  }
}

How it works:

The placeholder is replaced with the first list item
Additional items are inserted as new paragraphs
List formatting (bullet style, indentation) from the template is preserved

Formatting:

Use bullet lists, numbered lists, or plain paragraphs in your template
The placeholder's formatting is applied to all list items
Bold placeholder → All items bold
Italic placeholder → All items italic

Output Configuration

Control the output format and filename:

{
  "output": {
    "filename": "invoice-2024-001",
    "type": "pdf"
  }
}

Properties:

filename: Output filename without extension (optional)
- Pattern: ^[a-zA-Z0-9_-]+$
- Default: Template name + timestamp
type: Output format (optional)
- "pdf": Print-ready PDF (default)
- "docx": Editable Word document

API Workflow

1. Upload Template

curl -X POST 'https://api.json2doc.com/v1/templates/upload' \
  -H 'x-api-key: YOUR_API_KEY' \
  -F 'file=@template.docx' \
  -F 'name="My Template"'

2. (Optional) Upload Images

If using images, upload them first:

curl -X POST 'https://api.json2doc.com/v1/files/upload' \
  -H 'x-api-key: YOUR_API_KEY' \
  -F 'file=@logo.png' \
  -F 'category=image'

Save the returned path for use in your variables.

3. Generate Document

curl -X POST 'https://api.json2doc.com/v1/templates/generate' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d @variables.json

4. Download Result

curl -H "x-api-key: YOUR_API_KEY" \
  -o output.pdf \
  https://api.json2doc.com/v1/jobs/{jobId}/download

Best Practices

Descriptive variable names: Use {{customerName}} not {{cn}}
Format in template: Apply bold/italic/colors to placeholders in Word
Test incrementally: Start with text variables, then add images/tables/lists
Upload images first: Get file paths before generating documents
Use table variables: More efficient than multiple individual variables

Limits

Variables per template: 50 max
Table rows: 100 max per table
List items: 50 max per list
Image size: 10MB max per image
Template file: 100MB max

Next Steps

Examples - Complete invoice example with all features
API Reference - Full API documentation

Complete Invoice Example​

Template with Placeholders

Generated Invoice

Template Configuration​

Generate Documents​

Variable Types​

Automatic Type Detection (NEW ✨)​

1. Text Variables​

2. Image Variables​

3. QR Code Variables​

4. Table Variables​

5. List Variables​

Output Configuration​

API Workflow​

1. Upload Template​

2. (Optional) Upload Images​

3. Generate Document​

4. Download Result​

Best Practices​

Limits​

Next Steps​

Complete Invoice Example

Template Configuration

Generate Documents

Variable Types

Automatic Type Detection (NEW ✨)

1. Text Variables

2. Image Variables

3. QR Code Variables

4. Table Variables

5. List Variables

Output Configuration

API Workflow

1. Upload Template

2. (Optional) Upload Images

3. Generate Document

4. Download Result

Best Practices

Limits

Next Steps