Skip to main content
PPDF123

Overlay One PDF on Another

Overlay PDFs draws the pages of one or more overlay PDFs on top of, or behind, the pages of a base PDF. Overlay pages repeat when there are fewer than base pages, and are stretched to each base page.

Drag and drop files here, or click to choose

Accepts PDF · up to 500.0 MB per file · up to 20 files at once

You can also paste a file with Ctrl/Cmd+V, or from the clipboard menu.

Overlay PDFs merges the overlay files with qpdf, then stamps each overlay page as a Form XObject onto the base document. `overlayPosition` 0 is foreground, 1 is background. Overlay pages cycle with `i % overlay_len` (every base page gets an overlay, repeating the overlay file if it is shorter).

`overlayMode` is read and then ignored. Sequential, interleaved, and fixed-repeat labels do not change that modulo cycle. Missing overlay files are rejected with a bad-request error.

Scaling maps each overlay page onto the base page box. Password-protected files are unlocked for you on this page once you enter the password; API callers run Unlock first.

This is not Merge (concatenation) and not a transparency designer. For a single image stamp, Add Image is the closer tool.

Features

  • qpdf-merge overlays, then Form XObject onto every base page
  • `overlayPosition` foreground/background; `overlayMode` ignored
  • Short overlay packs repeat via modulo
  • Anonymous API at /api/v1/general/overlay-pdfs

When to use this tool

  • Stamp a letterhead PDF onto every page of a letter
  • Put a draft overlay in the background
  • Repeat a one-page confidential mark across a long file

How do I overlay one PDF on another?

  1. Upload the base PDF.
  2. Add one or more overlay PDFs. Choose foreground (0) or background (1).
  3. Ignore overlayMode; it does not change cycling.
  4. Download and check a page where the overlay should show.

Limits and edge cases

  • overlayMode is a dead field
  • The output is rebuilt page by page: links, form fields, bookmarks and metadata of the base PDF are not kept, and page rotation flags are dropped
  • Not Merge and not image-only (use Add Image)
  • Password-protected files need the password; API callers run Unlock first
  • Upload limit on this website: 500 MB per file, sent in chunks above about 95 MB. A single direct API request body is capped at 100 MB.

Examples

  • A 1-page overlay on a 10-page base marks all ten pages
  • Position 1 draws the overlay under existing content

Privacy for this tool

Files are uploaded over HTTPS, processed in memory or a short-lived temporary directory on our servers, and deleted when your result is ready. We do not keep copies for later browsing, training, or advertising profiles. See the Privacy Policy for retention details and AdSense cookie disclosures.

Frequently asked questions

What if the overlay has fewer pages than the base?
Overlays repeat. Page 5 of a 1-page overlay still gets that one overlay page.
Does interleaved mode interleave files?
No. overlayMode is discarded. Cycling is always i modulo overlay length.
Is this the same as Merge?
No. Merge concatenates. Overlay draws overlay pages on top of or under existing pages.
What if I forget overlay files?
The request fails with a bad-request error: at least one overlay file is required.

Last updated:

Call this from code

Every tool on this site is a plain REST endpoint - no account or API key needed for anonymous use. Built for AI agents and developers as much as for browsers.

curl -X POST "https://pdf123.xyz/api/v1/general/overlay-pdfs" \
  -F "[email protected]" \
  -F "[email protected]" \
  -F "overlayMode=SequentialOverlay" \
  -F "overlayPosition=0" \
  -o output.pdf

Also available as an MCP tool for agent clients that speak Model Context Protocol (JSON-RPC 2.0 over POST /mcp). Full API reference

Use it from an AI agent

Skill

Claude Code, Codex, Cursor and other AI agents can run Overlay PDFs for you with this skill: /skills/pdf123-overlay-pdfs.md

All agent skills

Files are used only for this processing job and deleted automatically afterward.