Add Image Stamp to PDF - Watermark API

PDF4me Add Image Stamp to PDF enables you to add customizable image stamps and watermarks to PDF documents. This API service processes PDF files and adds image watermarks with precise positioning, custom sizing, and formatting options for document branding and security. The API receives PDF content and image data through REST API calls, utilizing Base64 encoding for secure transmission. With support for flexible positioning, custom sizing, page targeting, and print control, this solution is ideal for document branding, copyright protection, and enterprise PDF workflows.

Authenticating Your API Request

To access the PDF4me REST API, every request must include proper authentication credentials. Authentication ensures secure communication and validates your identity as an authorized user of the REST API.

Get your api Key

Key Features

• Image Watermark Support: Add custom images as watermarks and stamps to PDF documents
• Flexible Positioning: Control horizontal and vertical alignment with pixel-perfect accuracy
• Custom Sizing: Adjust image dimensions using both millimeter and pixel measurements
• Advanced Formatting: Set opacity, margins, and background options for professional appearance
• Page Targeting: Apply stamps to specific pages or entire documents
• Print Control: Configure stamps to appear only in print or on screen
• Professional Results: Create image watermarks that enhance document security and branding
• Seamless API Integration: RESTful API designed for automated PDF editing workflows and enterprise system integration

REST API Endpoint

The PDF4me REST API uses standard HTTP methods to interact with resources. All image stamp addition operations are performed through a single endpoint:

• Method: POST
• Endpoint: /api/v2/ImageStamp

Image Stamping Features

Image Format Support

• Common Formats: Support for JPG, PNG, GIF, and other standard image formats
• Base64 Encoding: Secure image transmission through Base64 encoding
• Size Control: Both millimeter (10-200mm) and pixel-based (20-600px) sizing options

Positioning and Layout

• Horizontal Alignment: Left, Center, or Right positioning options
• Vertical Alignment: Top, Middle, or Bottom placement control
• Margin Control: Precise positioning with both millimeter (0-100mm) and pixel-based (0-300px) measurements
• Page Targeting: Apply to specific pages using page options (empty string for all pages, "1", "1,3,5", "2-5", "1,3,7-10", "2-")

Advanced Features

• Opacity Control: Adjustable transparency (0-100): 0=invisible, 100=fully opaque
• Background Mode: Option to place images behind (isBackground: true) or in front (isBackground: false) of content
• Print Control: Configure stamps to appear only in print (showOnlyInPrint: true) or in view and print (showOnlyInPrint: false)
• Asynchronous Processing: Support for async processing with polling for long-running operations

REST API Parameters

Complete list of parameters for the Add Image Stamp to PDF REST API. Parameters are organized by category for better understanding and implementation.

Important: Parameters marked with an asterisk (*) are required and must be provided for the API to function correctly.

Required Parameters

Parameter	Type	Description	Example
docName*	String	Output PDF file name with .pdf extension	output.pdf
docContent*	Base64	The content of the input PDF file encoded in Base64	JVBERi...
imageName*	String	Image file name with extension (e.g., .png, .jpg)	stamp.png
imageFile*	Base64	Image file content encoded in Base64 format	iVBORw0KGgoAAAANS...
alignX*	String	Horizontal alignment: Left, Center, or Right	Center
alignY*	String	Vertical alignment: Top, Middle, or Bottom	Middle

Optional Parameters

Parameter	Type	Description	Example
pages	String	Page options: empty string for all pages, "1" for page 1, "1,3,5" for specific pages, "2-5" for page range, "1,3,7-10" for mixed, "2-" for pages from 2 to end	"" or "1-3"
heightInMM	String	Image height in millimeters (10-200)	30
widthInMM	String	Image width in millimeters (10-200)	30
heightInPx	String	Image height in pixels (20-600)	85
widthInPx	String	Image width in pixels (20-600)	85
marginXInMM	String	Horizontal margin in millimeters (0-100)	10
marginYInMM	String	Vertical margin in millimeters (0-100)	10
marginXInPx	String	Horizontal margin in pixels (0-300)	28
marginYInPx	String	Vertical margin in pixels (0-300)	28
opacity	Integer	Opacity level (0-100): 0=invisible, 100=fully opaque	50
isBackground	Boolean	Place stamp in background (true) or foreground (false)	true
showOnlyInPrint	Boolean	Show only in print (true) or in view and print (false)	false
async	Boolean	Enable asynchronous processing. When true, the API returns a 202 status and provides a polling URL in the Location header	true

Output

The PDF4me Add Image Stamp to PDF REST API returns different responses based on the processing mode. The API returns the PDF as a Base64-encoded string in JSON format, not as binary data.

Success Response

Synchronous Processing (Default)

When async is not set or set to false, the API processes the request immediately:

Status Code: 200 OK

Content-Type: application/json

Response Body:

{
  "docName": "output.pdf",
  "docContent": "JVBERi0xLjQKJeLjz9MKMSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZwovUGFnZXMgMiAwIFIKPj4KZW5kb2JqCjIgMCBvYmoKPDwKL1R5cGUgL1BhZ2VzCi9LaWRzIFszIDAgUl0KL0NvdW50IDEKPD4KZW5kb2JqCjMgMCBvYmoKPDwKL1R5cGUgL1BhZ2UKL1BhcmVudCAyIDAgUgovTWVkaWFCb3ggWzAgMCA2MTIgNzkyXQovUmVzb3VyY2VzIDw8Ci9Gb250IDw8Ci9GMSA0IDAgUgo+Pgo+PgovQ29udGVudHMgNSAwIFIKPj4KZW5kb2JqCjQgMCBvYmoKPDwKL1R5cGUgL0ZvbnQKL1N1YnR5cGUgL1R5cGUxCi9CYXNlRm9udCAvSGVsdmV0aWNhCj4+CmVuZG9iago1IDAgb2JqCjw8Ci9MZW5ndGggNDQKPj4Kc3RyZWFtCkJUCi9GMSAxMiBUZgoxMDAgNzAwIFRkCihIZWxsbyBXb3JsZCkgVGoKRVQKZW5kc3RyZWFtCmVuZG9iagp4cmVmCjAgNgowMDAwMDAwMDAwIDY1NTM1IGYgCjAwMDAwMDAwMDkgMDAwMDAgbiAKMDAwMDAwMDA1NCAwMDAwMCBuIAowMDAwMDAwMTAxIDAwMDAwIG4gCjAwMDAwMDAxNzAgMDAwMDAgbiAKMDAwMDAwMDI0NCAwMDAwMCBuIAp0cmFpbGVyCjw8Ci9TaXplIDYKL1Jvb3QgMSAwIFIKPj4Kc3RhcnR4cmVmCjM0MQolJUVPRg=="
}

Response Fields:

• docName (string): The output PDF file name
• docContent (string): The PDF file with image stamp applied, encoded as Base64 string

How to Use:

1. Extract the docContent field from the JSON response
2. Decode the Base64 string to get the binary PDF data
3. Save or process the PDF file as needed

Example (JavaScript):

const response = await fetch(url, options);
const data = await response.json();
const pdfBytes = atob(data.docContent); // Decode Base64
// Save or process pdfBytes

Asynchronous Processing

Asynchronous Processing

When async: true is set, the API processes the request asynchronously:

Status Code: 202 Accepted

Response Headers:

Location: https://api.pdf4me.com/api/v2/ImageStamp/poll/12345-abcde-67890

Polling Process:

1. Extract the Location header from the 202 response
2. Poll the URL using GET requests
3. Continue polling until you receive a 200 OK status
4. The final response contains the same JSON format with docName and docContent (Base64)

Polling Example:

// Initial request returns 202 with Location header
const response = await fetch(url, options);
const location = response.headers.get('Location');

// Poll until complete
while (true) {
  const pollResponse = await fetch(location, { headers: { 'Authorization': 'Basic ' + apiKey } });
  if (pollResponse.status === 200) {
    const data = await pollResponse.json();
    // Process data.docContent (Base64 PDF)
    break;
  }
  await new Promise(resolve => setTimeout(resolve, 2000)); // Wait 2 seconds
}

Error Responses

Error Responses

The API returns standard HTTP error codes with error details:

400 Bad Request

• Invalid request parameters
• Missing required fields (docName, docContent, imageName, imageFile, alignX, alignY)
• Invalid Base64 encoding in docContent or imageFile
• Invalid alignment values (must be: Left/Center/Right for alignX, Top/Middle/Bottom for alignY)
• Invalid size or margin values (out of allowed ranges)

401 Unauthorized

• Invalid or missing API key
• API key not properly Base64 encoded in Authorization header
• Missing Authorization: Basic header

500 Internal Server Error

• Server-side processing error
• PDF processing failure
• Image stamp application failure

Error Response Format:

{
  "error": "Error message describing what went wrong"
}

Response Format Details

Response Format Details

Important: The API always returns JSON, never binary PDF data directly.

Response Structure:

{
  "docName": "string",      // Output PDF filename
  "docContent": "string"    // Base64-encoded PDF content
}

Content-Type Header:

• Success: application/json
• The PDF is embedded as a Base64 string within the JSON response

Why Base64?

• JSON-safe encoding for binary data
• Easy to transmit over HTTP
• Compatible with all programming languages
• Can be directly embedded in JSON without escaping issues

Decoding Base64 to PDF:

JavaScript/Node.js:

const base64 = response.docContent;
const binary = atob(base64); // Browser
// OR
const binary = Buffer.from(base64, 'base64').toString('binary'); // Node.js

Python:

import base64
pdf_bytes = base64.b64decode(response['docContent'])
with open('output.pdf', 'wb') as f:
    f.write(pdf_bytes)

C#:

byte[] pdfBytes = Convert.FromBase64String(response.docContent);
File.WriteAllBytes("output.pdf", pdfBytes);

Request Example

Header

Content-Type: application/json
Authorization: Basic YOUR_BASE64_ENCODED_API_KEY

Note:

• Get your API key from the PDF4me Dashboard
• The API key must be Base64 encoded and prefixed with "Basic " in the Authorization header
• Example: If your API key is abc123, encode it to Base64 and use Authorization: Basic YWJjMTIz

Payload

Basic Example (Required Fields Only):

{
  "docName": "output.pdf",
  "docContent": "JVBERi0xLjQKJeLjz9MKMSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZwovUGFnZXMgMiAwIFIKPj4KZW5kb2JqCjIgMCBvYmoKPDwKL1R5cGUgL1BhZ2VzCi9LaWRzIFszIDAgUl0KL0NvdW50IDEKPD4KZW5kb2JqCjMgMCBvYmoKPDwKL1R5cGUgL1BhZ2UKL1BhcmVudCAyIDAgUgovTWVkaWFCb3ggWzAgMCA2MTIgNzkyXQovUmVzb3VyY2VzIDw8Ci9Gb250IDw8Ci9GMSA0IDAgUgo+Pgo+PgovQ29udGVudHMgNSAwIFIKPj4KZW5kb2JqCjQgMCBvYmoKPDwKL1R5cGUgL0ZvbnQKL1N1YnR5cGUgL1R5cGUxCi9CYXNlRm9udCAvSGVsdmV0aWNhCj4+CmVuZG9iago1IDAgb2JqCjw8Ci9MZW5ndGggNDQKPj4Kc3RyZWFtCkJUCi9GMSAxMiBUZgoxMDAgNzAwIFRkCihIZWxsbyBXb3JsZCkgVGoKRVQKZW5kc3RyZWFtCmVuZG9iagp4cmVmCjAgNgowMDAwMDAwMDAwIDY1NTM1IGYgCjAwMDAwMDAwMDkgMDAwMDAgbiAKMDAwMDAwMDA1NCAwMDAwMCBuIAowMDAwMDAwMTAxIDAwMDAwIG4gCjAwMDAwMDAxNzAgMDAwMDAgbiAKMDAwMDAwMDI0NCAwMDAwMCBuIAp0cmFpbGVyCjw8Ci9TaXplIDYKL1Jvb3QgMSAwIFIKPj4Kc3RhcnR4cmVmCjM0MQolJUVPRg==",
  "imageName": "stamp.png",
  "imageFile": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==",
  "alignX": "Center",
  "alignY": "Middle"
}

Advanced Example (With All Optional Fields):

{
  "docName": "output.pdf",
  "docContent": "JVBERi0xLjQKJeLjz9MKMSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZwovUGFnZXMgMiAwIFIKPj4KZW5kb2JqCjIgMCBvYmoKPDwKL1R5cGUgL1BhZ2VzCi9LaWRzIFszIDAgUl0KL0NvdW50IDEKPD4KZW5kb2JqCjMgMCBvYmoKPDwKL1R5cGUgL1BhZ2UKL1BhcmVudCAyIDAgUgovTWVkaWFCb3ggWzAgMCA2MTIgNzkyXQovUmVzb3VyY2VzIDw8Ci9Gb250IDw8Ci9GMSA0IDAgUgo+Pgo+PgovQ29udGVudHMgNSAwIFIKPj4KZW5kb2JqCjQgMCBvYmoKPDwKL1R5cGUgL0ZvbnQKL1N1YnR5cGUgL1R5cGUxCi9CYXNlRm9udCAvSGVsdmV0aWNhCj4+CmVuZG9iago1IDAgb2JqCjw8Ci9MZW5ndGggNDQKPj4Kc3RyZWFtCkJUCi9GMSAxMiBUZgoxMDAgNzAwIFRkCihIZWxsbyBXb3JsZCkgVGoKRVQKZW5kc3RyZWFtCmVuZG9iagp4cmVmCjAgNgowMDAwMDAwMDAwIDY1NTM1IGYgCjAwMDAwMDAwMDkgMDAwMDAgbiAKMDAwMDAwMDA1NCAwMDAwMCBuIAowMDAwMDAwMTAxIDAwMDAwIG4gCjAwMDAwMDAxNzAgMDAwMDAgbiAKMDAwMDAwMDI0NCAwMDAwMCBuIAp0cmFpbGVyCjw8Ci9TaXplIDYKL1Jvb3QgMSAwIFIKPj4Kc3RhcnR4cmVmCjM0MQolJUVPRg==",
  "imageName": "stamp.png",
  "imageFile": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==",
  "alignX": "Center",
  "alignY": "Middle",
  "pages": "",
  "heightInMM": "30",
  "widthInMM": "30",
  "heightInPx": "85",
  "widthInPx": "85",
  "marginXInMM": "10",
  "marginYInMM": "10",
  "marginXInPx": "28",
  "marginYInPx": "28",
  "opacity": 50,
  "isBackground": true,
  "showOnlyInPrint": false,
  "async": true
}

Code Samples

The PDF4me Add Image Stamp to PDF REST API provides code samples in multiple programming languages. Choose the language that best fits your development environment:

C#

C# (CSharp) Sample

Complete C# implementation for adding image stamps to PDF:

View C# Sample

Java

Java Sample

Java implementation with full error handling and response processing:

View Java Sample

JavaScript

JavaScript Sample

Node.js and browser-compatible JavaScript implementation:

View JavaScript Sample

Python

Python Sample

Python implementation with requests library and JSON handling:

View Python Sample

Salesforce

Salesforce Sample

Salesforce Apex implementation for CRM integration:

View Salesforce Sample

n8n

n8n Sample

n8n workflow implementation for automation:

View n8n Sample

Google Script

Google Script Sample

Google Apps Script implementation for Google Workspace integration:

View Google Script Sample

AWS Lambda

AWS Lambda Sample

Serverless AWS Lambda function implementation:

View AWS Lambda Sample

Industry Use Cases & Applications

Legal & Professional Services

Legal & Professional Services Use Cases

• Legal Documentation: Apply legal disclaimers and confidentiality notices to legal documents
• Contract Stamping: Add image stamps to contracts and agreements
• Confidentiality Notices: Apply confidentiality image stamps to sensitive legal documents
• Compliance Stamps: Add regulatory compliance image notices to legal documents

Business & Enterprise

Business & Enterprise Use Cases

• Document Branding: Add company logos, watermarks, and branding elements to PDF documents
• Status Indicators: Add "DRAFT", "CONFIDENTIAL", or "APPROVED" image stamps to indicate document status
• Report Generation: Add timestamps, page numbers, and report identifiers to generated documents
• Corporate Branding: Apply consistent image branding across business documents

Finance & Banking

Finance & Banking Use Cases

• Financial Reports: Add image stamps to financial reports and statements
• Invoice Stamping: Apply approval image stamps to invoices and purchase orders
• Compliance Documentation: Add regulatory image stamps to financial documents
• Audit Trails: Create audit trails with image timestamp stamps on financial documents

Government & Compliance

Government & Compliance Use Cases

• Copyright Protection: Apply copyright notices and ownership image stamps to protect intellectual property
• Regulatory Compliance: Add compliance image stamps to meet regulatory requirements
• Official Documentation: Apply official image stamps to government documents
• Public Records: Add classification image stamps to public records and documents

Get Help

Get Your API KeyAPI SamplesGetting Started