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.
When you upload several overlay files they are joined in the order you added them into one overlay sequence, and the page cycle runs across that combined sequence. Two overlay files of 1 page each therefore alternate on base pages 1, 2, 3, and so on.
The horizontal and vertical scale factors are computed separately, so an overlay page with a different shape from the base page is stretched to fill it rather than centered with its proportions kept. Use overlay pages cut to the same size as the base for predictable results.
Anything other than `overlayPosition` 1 puts the overlay on top. A value that is not a whole number is rejected with an error saying it must be an integer. The result is named after the base upload with a `.pdf` extension.
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
- Alternate a front-page template and a continuation-page template with two one-page overlay files
- Lay a ruled or branded background under scanned pages
How do I overlay one PDF on another?
- Upload the base PDF.
- Add one or more overlay PDFs. Choose foreground (0) or background (1).
- Ignore overlayMode; it does not change cycling.
- Download and check a page where the overlay should show.
- If the overlay hides the content, rerun with position 1 so it draws underneath. If it disappears behind opaque base content, rerun with position 0 so it draws on top.
- If an overlay shows on the wrong pages, split your overlay into single-page files in the order you want, upload them in that order, and run again, since the cycle follows overlay order.
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
- A 3-page overlay on a 7-page base puts overlay pages 1, 2, 3, 1, 2, 3, 1 on base pages 1 to 7
- Uploading `contract.pdf` as the base and `letterhead.pdf` as the overlay returns `contract.pdf` with the letterhead on each page
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.
- Can I use more than one overlay file?
- Yes. The files are joined in upload order into one sequence, and base page N gets overlay page N modulo the total overlay page count. Two one-page overlays alternate on odd and even base pages.
- Why does my overlay look stretched?
- The overlay page is scaled to the base page width and height independently. If the two pages have different aspect ratios, the overlay is distorted. Prepare the overlay at the base page size.
- Will my links, form fields and bookmarks survive?
- No. The output is rebuilt page by page from the page content, so interactive elements and bookmarks of the base PDF are not kept. Run Overlay before you add forms or links.
- When should I use Watermark or Add Image instead?
- Use Watermark for a text mark and Add Image for a picture. Overlay is for placing whole PDF pages, such as a letterhead or a form template, behind or over the base.
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.pdfAlso 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
SkillClaude Code, Codex, Cursor and other AI agents can run Overlay PDFs for you with this skill: /skills/pdf123-overlay-pdfs.md
Files are used only for this processing job and deleted automatically afterward.