Watermark and stamp

A watermark goes behind the page content, a stamp on top of it. Both can be text, an image or a page of another PDF.

POST https://api.pdfdispatch.com/v1/pdf/watermark

POST https://api.pdfdispatch.com/v1/pdf/stamp

Form fields

The two routes are the same except for the prefix: watermark... on the first, stamp... on the second.

Field	Type	Default	What it does
`files` required	file(s)	–	The PDFs to mark.
`watermarkSource / stampSource` required	string	–	`text`, `image` or `pdf`.
`watermarkExpression / stampExpression`	string	–	For `text`, the text itself. For `image` and `pdf`, leave it out and send the file instead (below).
`watermark / stamp`	file	–	The image (PNG, JPEG, …) or PDF to draw, as a file part with this name.
`watermarkPages / stampPages`	string	–	Only these pages, for example `1`, `2-`, `odd`. All pages without it.
`watermarkOptions / stampOptions`	JSON object	–	How it looks; see the table below.

To apply several in one request, repeat the fields: the first stampSource goes with the first stampExpression, stampPages and stampOptions, the second with the second, and so on. Image and PDF entries take the uploaded stamp (or watermark) files in order. The same fields work on every conversion route.

Options

watermarkOptions and stampOptions are a JSON object of the keys below. Every value is a string, numbers too ("points": "48", not "points": 48); a bare number is refused with 400. Leave out what you do not need.

Key	Type	Default	What it does
`fontname`	string	`Helvetica`	One of the 14 standard PDF fonts: `Helvetica`, `Times-Roman`, `Courier`, their `-Bold` and `-Oblique` (or `-Italic`) forms, `Symbol`, `ZapfDingbats`.
`points`	number	`24`	Font size.
`scalefactor`	string	`0.5 rel`	Size as a share of the page: `0.5 rel` is half the page width; `1 abs` keeps the natural size.
`rotation`	number	–	Angle in degrees, counter-clockwise. Without it, the mark runs along the diagonal (see `diagonal`): send `"0"` for a level stamp or logo.
`diagonal`	integer	`1`	`1` from bottom left to top right, `2` from top left to bottom right.
`position`	string	`c`	Where on the page: `c` (centre), `tl`, `tc`, `tr`, `l`, `r`, `bl`, `bc`, `br`.
`offset`	string	`0 0`	Move it from that position, in points: `"-20 30"`.
`fillcolor`	colour	`#808080`	Text colour, as `#rrggbb` or a name such as `red`.
`opacity`	number	`1`	From `0` (invisible) to `1` (solid).
`aligntext`	string	`center`	`left`, `center`, `right` or `justify`, for text over several lines (`\n` in the expression).
`backgroundcolor, bordercolor, border, margins`	various	–	A box behind the text, with its colour, border and spacing.

Examples

“DRAFT” diagonally behind every page:

curl --fail-with-body \
  --header "Authorization: Bearer $PDD_KEY" \
  --form files=@contract.pdf \
  --form watermarkSource=text \
  --form watermarkExpression=DRAFT \
  --form 'watermarkOptions={"fontname": "Helvetica-Bold", "points": "96", "fillcolor": "#c2410c", "opacity": "0.15"}' \
  --output contract-draft.pdf \
  https://api.pdfdispatch.com/v1/pdf/watermark

A “PAID” stamp in the top right corner of the first page, and a logo at the bottom of every page, in one request:

curl --fail-with-body \
  --header "Authorization: Bearer $PDD_KEY" \
  --form files=@invoice.pdf \
  --form stampSource=text \
  --form stampExpression=PAID \
  --form stampPages=1 \
  --form 'stampOptions={"position": "tr", "offset": "-40 -40", "rotation": "15", "points": "28", "fillcolor": "#15803d", "scalefactor": "1 abs"}' \
  --form stampSource=image \
  --form 'stampOptions={"position": "bc", "rotation": "0", "scalefactor": "0.15 rel", "offset": "0 20"}' \
  --form stamp=@logo.png \
  --output invoice-paid.pdf \
  https://api.pdfdispatch.com/v1/pdf/stamp

Fields are matched by position. The second entry has no stampExpression and no stampPages, which works because nothing comes after it. When an earlier entry has no value for a field that a later one uses, send that field empty for it (--form stampPages=), so the positions still line up.

For Office files, the Office route can also draw a simple text watermark itself while converting (nativeWatermarkText, see Office documents).