Watermark PDF

Add text or image watermarks to PDF documents with customizable positioning and styling.

POSThttps://api.morphopdf.com/v1/pdf/watermark

Authentication

AuthorizationBearer

Retrieve your API Key from Dashboard.

Request Body

One input source is required (file, fileBase64, or url).

fileFile

The PDF file to watermark, uploaded via multipart/form-data.

fileBase64string

Base64-encoded PDF content as an alternative to file upload.

urlstring

Public URL of PDF file to fetch and watermark.

Watermark Configuration

watermarkTypestring

Type of watermark: 'text' or 'image'.

watermarkOptionsobject

Configuration object for the watermark (see options below).

pagesstring | number[]OptionalDefault: all

Pages to watermark: 'all' or array of 1-based page numbers [1, 3, 5].

Text Watermark Options

When watermarkType is 'text':

textstring

The watermark text to display.

fontSizenumberOptionalDefault: 48

Font size in points.

colorstringOptionalDefault: #000000

Hex color code for the text.

opacitynumberOptionalDefault: 0.3

Transparency level from 0 (invisible) to 1 (solid).

positionstringOptionalDefault: center

Placement: 'top-left', 'top-center', 'top-right', 'middle-left', 'center', 'middle-right', 'bottom-left', 'bottom-center', 'bottom-right', or 'custom'.

rotationnumberOptionalDefault: -45

Rotation angle in degrees. Use -45 for diagonal watermarks.

customXnumberOptional

X position as percentage (0-100) when position='custom'.

customYnumberOptional

Y position as percentage (0-100) when position='custom'.

Image Watermark Options

When watermarkType is 'image':

imageDatastringOptional

Base64-encoded PNG or JPEG image data.

imageUrlstringOptional

Public URL of the watermark image to fetch.

widthnumberOptional

Width of the watermark image in points.

heightnumberOptional

Height of the watermark image in points.

opacitynumberOptionalDefault: 0.3

Transparency level from 0 (invisible) to 1 (solid).

positionstringOptionalDefault: center

Same position options as text watermarks.

rotationnumberOptionalDefault: 0

Rotation angle in degrees.

Common Watermark Patterns

Diagonal text: Use rotation: -45 with position: center
Logo in corner: Use image type with position: bottom-right
Subtle branding: Use low opacity (0.1-0.3)

Image URL Requirements

When using imageUrl, the image must be publicly accessible. The API will fetch the image with a 15-second timeout and 10MB size limit.

Query Parameters

formatstringOptionalDefault: json

Response format. Use 'binary' to receive the watermarked PDF file directly, or 'json' (default) to receive metadata with a download URL.

Response

When using format=json (default):

successboolean

Indicates whether the operation completed successfully.

messagestring

Human-readable status message.

fileNamestring

Name of the watermarked PDF file.

downloadUrlstring

Presigned URL to download the file. Valid for 1 hour.

pagesWatermarkednumber

Number of pages that received the watermark.

Error Responses

Status	Code	Description
400	`INVALID_INPUT`	Missing required fields or invalid watermark type
400	`URL_FETCH_FAILED`	Failed to fetch watermark image from URL
413	`FILE_TOO_LARGE`	File exceeds maximum size (50MB)
500	`PROCESSING_FAILED`	Watermark operation failed

POST/v1/pdf/watermark

curl -X POST "https://api.morphopdf.com/v1/pdf/watermark?format=binary" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@document.pdf" \
  -F "watermarkType=text" \
  -F 'watermarkOptions={"text": "CONFIDENTIAL", "fontSize": 48, "color": "#FF0000", "opacity": 0.3, "position": "center", "rotation": -45}' \
  --output watermarked.pdf

200OK

{
  "success": true,
  "message": "File processed successfully",
  "fileName": "watermarked.pdf",
  "downloadUrl": "https://files.morphopdf.com/sessions/abc123/output/watermarked.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=3600&...",
  "pagesWatermarked": 10
}