Watermarking

Add watermarks to your PDFs for branding, security, or document status indication. Supports both text and image watermarks with full customization.

Text Watermarks

Add text overlays to every page of your PDF with customizable font size, opacity, rotation, color, and position.

Basic Example

const formData = new FormData();

const htmlContent = `
  <!DOCTYPE html>
  <html>
    <body style="font-family: Arial; padding: 40px;">
      <h1>Confidential Report</h1>
      <p>This document contains sensitive information...</p>
    </body>
  </html>
`;

formData.append('files', new Blob([htmlContent], { type: 'text/html' }), 'index.html');
formData.append('options', JSON.stringify({
  fileName: 'confidential-report',
  format: 'A4',
  watermark: {
    text: 'CONFIDENTIAL',
    fontSize: 60,
    opacity: 0.2,
    rotation: -45,
    color: { r: 1, g: 0, b: 0 },
    position: 'diagonal'
  }
}));

const response = await fetch('https://api.syntaxdoc.com/pdf/generate', {
  method: 'POST',
  headers: { 'X-API-Key': 'YOUR_API_KEY' },
  body: formData
});

const pdfBlob = await response.blob();

import requests
import json

html_content = '''
<!DOCTYPE html>
<html>
  <body style="font-family: Arial; padding: 40px;">
    <h1>Confidential Report</h1>
    <p>This document contains sensitive information...</p>
  </body>
</html>
'''

files = {
    'files': ('index.html', html_content, 'text/html')
}

options = {
    'fileName': 'confidential-report',
    'format': 'A4',
    'watermark': {
        'text': 'CONFIDENTIAL',
        'fontSize': 60,
        'opacity': 0.2,
        'rotation': -45,
        'color': {'r': 1, 'g': 0, 'b': 0},
        'position': 'diagonal'
    }
}

response = requests.post(
    'https://api.syntaxdoc.com/pdf/generate',
    headers={'X-API-Key': 'YOUR_API_KEY'},
    files=files,
    data={'options': json.dumps(options)}
)

with open('confidential-report.pdf', 'wb') as f:
    f.write(response.content)

curl -X POST https://api.syntaxdoc.com/pdf/generate \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "files=@document.html" \
  -F 'options={"fileName":"confidential-report","format":"A4","watermark":{"text":"CONFIDENTIAL","fontSize":60,"opacity":0.2,"rotation":-45,"color":{"r":1,"g":0,"b":0},"position":"diagonal"}}' \
  --output confidential-report.pdf

Watermark Options

All watermark options are specified in the watermark object within options:

Option	Type	Default	Description
`text`	string	`"WATERMARK"`	Text to display
`fontSize`	number	`48`	Font size in points
`opacity`	number	`0.3`	Opacity (0.0 = invisible, 1.0 = solid)
`rotation`	number	`-45`	Rotation angle in degrees
`color`	object	`{r:0.5, g:0.5, b:0.5}`	RGB color (0.0 to 1.0)
`position`	string	`"diagonal"`	Position on page (see below)

Position Options

diagonal - Centered diagonally across page (default)
center - Centered horizontally and vertically
top-left - Top left corner
top-right - Top right corner
bottom-left - Bottom left corner
bottom-right - Bottom right corner

Common Use Cases

Draft Documents

watermark: {
  text: 'DRAFT',
  fontSize: 72,
  opacity: 0.15,
  rotation: -45,
  color: { r: 0.5, g: 0.5, b: 0.5 },
  position: 'diagonal'
}

Confidential Documents

watermark: {
  text: 'CONFIDENTIAL',
  fontSize: 60,
  opacity: 0.2,
  rotation: -45,
  color: { r: 1, g: 0, b: 0 },
  position: 'diagonal'
}

Sample/Preview Documents

watermark: {
  text: 'SAMPLE',
  fontSize: 80,
  opacity: 0.1,
  rotation: 0,
  color: { r: 0, g: 0, b: 0 },
  position: 'center'
}

Copyright Notice

watermark: {
  text: '© 2024 Your Company',
  fontSize: 12,
  opacity: 0.5,
  rotation: 0,
  color: { r: 0, g: 0, b: 0 },
  position: 'bottom-right'
}

Page Numbers Alternative

watermark: {
  text: 'Page 1',
  fontSize: 10,
  opacity: 0.7,
  rotation: 0,
  color: { r: 0, g: 0, b: 0 },
  position: 'bottom-right'
}

Color Reference

Colors use RGB values from 0.0 to 1.0:

Color	RGB Object
Black	`{ r: 0, g: 0, b: 0 }`
White	`{ r: 1, g: 1, b: 1 }`
Red	`{ r: 1, g: 0, b: 0 }`
Green	`{ r: 0, g: 1, b: 0 }`
Blue	`{ r: 0, g: 0, b: 1 }`
Gray	`{ r: 0.5, g: 0.5, b: 0.5 }`
Yellow	`{ r: 1, g: 1, b: 0 }`
Orange	`{ r: 1, g: 0.5, b: 0 }`
Purple	`{ r: 0.5, g: 0, b: 0.5 }`

For light colors, use higher opacity (0.5-0.7). For dark colors, use lower opacity (0.1-0.3) to avoid obscuring content.

Batch Watermarking

Apply the same watermark to multiple PDFs in a batch:

const response = await fetch('https://api.syntaxdoc.com/pdf/generate-batch', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    documents: [
      { fileName: 'invoice-001', htmlContent: '<html>...</html>' },
      { fileName: 'invoice-002', htmlContent: '<html>...</html>' },
      // More documents...
    ],
    options: {
      format: 'A4',
      watermark: {
        text: 'COPY',
        fontSize: 48,
        opacity: 0.2,
        rotation: -45
      }
    }
  })
});

The watermark is applied to all PDFs in the batch. Each PDF will have identical watermark styling.

Advanced Techniques

Dynamic Watermarks

Generate different watermarks per document:

const invoices = [
  { id: '001', status: 'PAID' },
  { id: '002', status: 'PENDING' },
  { id: '003', status: 'OVERDUE' }
];

for (const invoice of invoices) {
  const formData = new FormData();
  formData.append('files', htmlBlob, 'index.html');
  
  formData.append('options', JSON.stringify({
    fileName: `invoice-${invoice.id}`,
    watermark: {
      text: invoice.status,
      fontSize: 48,
      opacity: 0.25,
      color: invoice.status === 'PAID' 
        ? { r: 0, g: 1, b: 0 }  // Green
        : { r: 1, g: 0, b: 0 }  // Red
    }
  }));
  
  await fetch('https://api.syntaxdoc.com/pdf/generate', {
    method: 'POST',
    headers: { 'X-API-Key': 'YOUR_API_KEY' },
    body: formData
  });
}

Conditional Watermarks

Add watermarks only for certain conditions:

function generateInvoice(invoice, isPaid) {
  const options = {
    fileName: `invoice-${invoice.id}`,
    format: 'Letter'
  };
  
  // Only add watermark if not paid
  if (!isPaid) {
    options.watermark = {
      text: 'UNPAID',
      fontSize: 60,
      opacity: 0.2,
      color: { r: 1, g: 0, b: 0 }
    };
  }
  
  return options;
}

Multiple Text Lines

For multi-line watermarks, use line breaks:

watermark: {
  text: 'INTERNAL USE ONLY\nNOT FOR DISTRIBUTION',
  fontSize: 36,
  opacity: 0.15,
  rotation: -45
}

Best Practices

1. Opacity Guidelines

Subtle branding: 0.05 - 0.15
Draft/Sample: 0.15 - 0.25
Confidential: 0.2 - 0.3
Strong emphasis: 0.3 - 0.5

Opacity above 0.5 may significantly obscure document content. Test with your specific use case.

2. Font Size by Page Format

Format	Recommended Font Size
A4/Letter	48 - 72
A3	72 - 96
A5	36 - 48
Legal	60 - 80

3. Rotation Best Practices

Diagonal (-45°): Most common, least intrusive
Horizontal (0°): Best for footer/header watermarks
Vertical (90° or -90°): Good for side margins
Custom angles: Use sparingly, can look unprofessional

4. Performance

Watermarks add minimal processing time:

Single PDF: +50-100ms
Batch (100 PDFs): +5-10 seconds total

The performance impact is negligible compared to PDF generation itself.

Image Watermarks (Coming Soon)

Support for image-based watermarks (logos, signatures) is in development:

watermark: {
  image: imageBuffer,  // PNG or JPG buffer
  imageOpacity: 0.3,
  position: 'center'
}

Join our Discord community to be notified when this feature launches!

Troubleshooting

Watermark Not Visible

Check these settings:

Opacity too low: Try increasing to 0.3
Color matches background: Use contrasting colors
Font size too small: Increase to 48+
Position off-page: Use diagonal or center

Watermark Obscures Content

Solutions:

Reduce opacity: Try 0.1 - 0.2
Use lighter color: Gray instead of black
Change position: Move to corner instead of center
Adjust rotation: -45° is usually least intrusive

Watermark Position Unexpected

Watermark coordinates are based on PDF page size. For precise positioning, use:

Page format that matches your HTML
CSS @page size rules
preferCSSPageSize: true option

Examples Gallery

Professional Invoice

watermark: {
  text: 'COPY - NOT FOR PAYMENT',
  fontSize: 32,
  opacity: 0.2,
  rotation: 0,
  color: { r: 0, g: 0, b: 0 },
  position: 'top-right'
}

Legal Document

watermark: {
  text: 'ATTORNEY-CLIENT PRIVILEGE',
  fontSize: 18,
  opacity: 0.4,
  rotation: 0,
  color: { r: 0.2, g: 0.2, b: 0.2 },
  position: 'bottom-left'
}

Event Ticket

watermark: {
  text: 'ADMIT ONE',
  fontSize: 96,
  opacity: 0.08,
  rotation: -45,
  color: { r: 0.7, g: 0.7, b: 0.7 },
  position: 'diagonal'
}

Certificate of Completion

watermark: {
  text: 'AUTHENTIC',
  fontSize: 64,
  opacity: 0.05,
  rotation: 0,
  color: { r: 0.8, g: 0.6, b: 0.2 },
  position: 'center'
}

Watermarking

On this page