Add Watermark to Word

PDF4me Add Watermark to Word is a REST endpoint that stamps an image watermark behind the text of every page in a Word document. POST the .docx and the watermark image as Base64 to office/ApiV2Word/AddWatermark, tune scale, transparency, and alignment, then decode the watermarked file from the JSON response. PNG, JPG, JPEG, BMP, and GIF images are supported.

What this endpoint does

Takes a Word document plus an image and returns the same document with that image stamped behind the text of every section: a logo, a CONFIDENTIAL banner, a DRAFT stamp. You control the size (exact points or a scale factor), a 50 percent transparency toggle, and center versus top-left placement. The response is JSON with the result as Base64 content.

Authenticating Your API Request

Every PDF4me REST call must include your API key in the Authorization header as Basic auth. Get or rotate your key from the developer dashboard.

Get your API Key

Endpoint

POSToffice/ApiV2Word/AddWatermark

Postman URLhttps://api.pdf4me.com/office/ApiV2Word/AddWatermark

Important Facts You Should Not Miss

The response is Base64 JSON, not the file

The watermarked document comes back as a Base64 string inside a JSON body with fileName, success, and errorMessage. Decode it before saving; the raw response is not a valid .docx.

Width and height override scale

Sizing priority is exact width/height in points first, then scale, then the original image size. Send only one dimension and the other is calculated to keep the aspect ratio.

Behind the text, in every section

The image is stamped behind the document content across all sections and headers, so text stays readable. A transparent PNG plus semiTransparent: true gives the classic subtle-stamp look.

HTTP setup

Method: POST
URL: https://api.pdf4me.com/office/ApiV2Word/AddWatermark
Content-Type: application/json
Authorization: Basic <your PDF4me API key>

The response is JSON: check the success flag, then Base64-decode the returned document content and save it with a .docx extension.

How does watermark sizing priority work?

Three sizing inputs exist and they are strictly ranked. The API uses the highest-priority input you actually send and ignores the rest.

Sizing input vs behavior	When it applies	What the watermark gets
`width` and `height` (points)	Highest priority; overrides `scale` when present	Exactly the dimensions you specify. One dimension alone keeps the aspect ratio
`scale` (0.1 to 10.0)	Used only when no width or height is sent	Original image size multiplied by the factor: 0.5 is half size, 2.0 is double
Neither sent	Fallback	The original pixel dimensions of the uploaded image

API body fields

Parameter	Required	Type	What it does	Example
`document`	Required	object	Document reference carrying Name, the Word filename with its .docx extension.	`{ "Name": "document.docx" }`
`docContent`	Required	string	Base64-encoded bytes of the Word document to watermark.	`UEsDBBQABgAIAAAA...`
`watermarkFileName`	Required	string	Watermark image filename with its extension. PNG, JPG, JPEG, BMP, and GIF are supported.	`watermark.png`
`watermarkFileContent`	Required	string	Base64-encoded bytes of the watermark image. A PNG with a transparent background gives the cleanest behind-text result.	`iVBORw0KGgo...`
`scale`	Optional	number	Scale factor from 0.1 to 10.0 applied to the original image size. Default 1.0. Ignored when width or height is sent.	`1.5`
`semiTransparent`	Optional	boolean	true renders the watermark at 50 percent opacity for a subtle stamp; false (default) keeps full opacity.	`true`
`width`	Optional	number	Exact watermark width in points. Overrides scale. If height is omitted it is calculated to keep the aspect ratio.	`200`
`height`	Optional	number	Exact watermark height in points. Overrides scale. If width is omitted it is calculated to keep the aspect ratio.	`150`
`alignImage`	Optional	boolean	true (default) centers the watermark on the page; false aligns it top-left within the margins.	`true`
`cultureName`	Optional	string	Culture code applied to document metadata during processing, for example en-US or de-DE.	`en-US`

Sample payloads

Minimal request (required fields only)

{
 "document": { "Name": "document.docx" },
 "docContent": "UEsDBBQABgAIAAAA...",
 "watermarkFileName": "watermark.png",
 "watermarkFileContent": "iVBORw0KGgoAAAANSUhEUgAA..."
}

Sized, semi-transparent, centered

{
 "document": { "Name": "contract-draft.docx" },
 "docContent": "UEsDBBQABgAIAAAA...",
 "watermarkFileName": "confidential.png",
 "watermarkFileContent": "iVBORw0KGgoAAAANSUhEUgAA...",
 "width": 200,
 "height": 150,
 "semiTransparent": true,
 "alignImage": true,
 "cultureName": "en-US"
}

Postman collection tips

Headers

Content-Type: application/json + Authorization: Basic <apiKey>.

Body

raw JSON with TWO Base64 fields: docContent for the Word file and watermarkFileContent for the image. Both must be encoded separately.

Sizing

Send width/height OR scale, not both. If you send both, the exact dimensions win and scale is silently ignored.

Response

JSON with a success flag and Base64 document content. Decode the document field before saving as .docx.

curl example

curl -X POST https://api.pdf4me.com/office/ApiV2Word/AddWatermark \
 -H "Content-Type: application/json" \
 -H "Authorization: Basic YOUR_API_KEY" \
 -d '{
 "document": { "Name": "document.docx" },
 "docContent": "'"$(base64 -w 0 document.docx)"'",
 "watermarkFileName": "watermark.png",
 "watermarkFileContent": "'"$(base64 -w 0 watermark.png)"'",
 "semiTransparent": true
 }' \
 --output response.json

What does the API return?

A JSON result carrying the watermarked document as Base64.

Field	Type	What it contains
`document`	String (Base64)	The watermarked Word document content. Decode to bytes and save with a .docx extension.
`fileName`	String	Output filename for the watermarked document.
`success`	Boolean	true when watermarking succeeded. Check this before decoding content.
`errorMessage`	String	Populated when success is false: invalid Base64, a corrupted document or image, or out-of-range sizing values.

Asynchronous behavior (202 Accepted with a polling URL in the Location header) is controlled by server configuration, not by a request body parameter. When a 202 arrives, poll the Location URL with GET requests until you receive 200 OK with the same JSON shape.

Code samples

Word office endpoints are not yet covered by per-endpoint sample folders in the samples repository; it carries the request pattern used by every PDF4me endpoint family:

View API Samples Repository

FAQ

Which image formats can I use as a Word watermark?+

PNG, JPG, JPEG, BMP, and GIF. A PNG with a transparent background gives the cleanest result because the image is stamped behind the document text on every page.

Is the response the Word file itself?+

No. The API returns JSON containing the watermarked document as a Base64 string plus fileName, success, and errorMessage fields. Decode the document field to bytes before saving as .docx.

What happens if I send both scale and width or height?+

Width and height win. Exact dimensions in points always override the scale factor. If you provide only one of the two, the other is calculated automatically to preserve the image aspect ratio.

Does the watermark cover the document text?+

No. The watermark is placed behind the text, in every section of the document, so the content stays readable. Set semiTransparent to true for a subtle 50 percent opacity effect.

Can this endpoint add text watermarks like DRAFT or CONFIDENTIAL?+

This endpoint stamps images. For text stamps use the Add Text Watermark to Word endpoint, or render your text as a transparent PNG and pass it here as the watermark image.

Where does the watermark appear in the document?+

Across all sections and their headers, behind the content. alignImage true centers it on the page; false places it top-left within the margins. Per-page or per-range placement is not part of this action.

Does adding a watermark protect the document from editing?+

No. A watermark is a visual marker, not a security control; anyone who can edit the file can remove it. To restrict editing or require a password, chain the Secure Word Document endpoint after this one.

Why add watermarks via API instead of manually in Word?

The manual route is inserting a picture watermark in Word: open each file, Design tab, Watermark, Custom Watermark, pick the image, save, repeat. That does not scale to a contract pipeline that stamps every outgoing draft. The API applies the same behind-text stamp as one deterministic request per file, with exact point sizing that the Word dialog does not expose. The result is standard digital watermarking for provenance and status marking, applied at pipeline speed.

Add Text Watermark to Word

Stamp DRAFT or CONFIDENTIAL as styled text instead of an image.

Secure Word Document

Watermarks mark; passwords protect. Add real editing restrictions after stamping.

Replace Text with Image

Swap inline placeholders for images instead of stamping behind the page.