Merge PDF API
You're not "just combining files." You're trying to ship a workflow that won't break when a user uploads a random mix of A4 + Letter, rotates pages, or changes the order at the last second. This endpoint merges PDFs fast, preserves intent, and gives you predictable output—so you stop babysitting document joins. Need the full suite? Start with the PDF API.
Merge preview
A4 + Letter + mixed sources → one clean PDF
application-form.pdf
Letter • 3 pages
terms-and-consent.pdf
A4 • 2 pages
output.pdf
Same content. Correct order. Consistent sizing rules.
128,406,912
PDF pages merged in production workflows
47 minutes/day
average time saved per team by removing manual joins
99.95%
merge success rate across mixed page sizes & sources
You know the feeling when a "simple merge" becomes a support ticket.
Someone uploads two PDFs. You join them. Done… until page sizes don't match, margins jump, and the "first page" is suddenly in the middle because a user picked files in the wrong order. Then you're stuck debugging a document instead of building your product.
Order chaos
File pickers lie. Users drag-and-drop "close enough." Your output becomes a shuffled packet.
A4 + Letter weirdness
Mixed sizes create visual "jump cuts" that make forms look broken and unprofessional.
Costly rework
A single wrong merge can delay approvals, signatures, and onboarding—right when momentum matters.
There's a better way: merge with intent, not hope.
Use a dedicated combine PDF API endpoint that lets you explicitly set the merge order and decide what should happen when page sizes don't match. The result: stable output you can trust in production.
Endpoint
POST /v1/pdf/merge
Designed for joining files (a.k.a. concatenate PDF API behavior) with explicit ordering and page-size normalization rules.
order
Controls the exact sequence of input PDFs in the final output.
page_size_handling
Choose what happens when A4 meets Letter (more below).
Example request
cURLcurl -X POST "https://api.xspdf.com/v1/pdf/merge" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"output": { "filename": "packet.pdf" },
"inputs": [
{ "source_url": "https://files.example.com/application-form.pdf", "order": 1 },
{ "source_url": "https://files.example.com/terms-and-consent.pdf", "order": 2 },
{ "source_url": "https://files.example.com/signature-page.pdf", "order": 3 }
],
"page_size_handling": {
"mode": "fit",
"target": "largest"
}
}'Order is explicit
You set order per input. No guessing based on upload time, filenames, or UI quirks.
Mixed page sizes handled
Pick a rule once—then every merge behaves consistently, even with A4 + Letter in the same packet.
Page size handling (A4 + Letter): what actually works
When PDFs have different sizes, you have three sane strategies—each optimized for a different outcome:
- 1
Fit (recommended for packets)
Scale content to fit the target page without cropping. Best when "nothing can be cut off."
- 2
Crop (best for full-bleed designs)
Preserve scale and crop overflow. Use when design consistency matters more than edge content.
- 3
Keep (best for "as-is" archives)
Don't normalize sizes; keep each page's native dimensions. Great for compliance archives, less great for printing packets.
Tip: If you're merging application packets, "fit + target: largest" prevents accidental truncation when Letter meets A4.
What you get (the outcomes you actually care about)
Merging isn't the hard part. Shipping a merge that stays correct when users behave like users is the hard part. These are the safeguards that keep your "join files" feature quiet—in the best way.
Predictable packets
Every merge follows the same rules, so the output looks consistent across customers and time.
Fewer "where did my page go?" tickets
Explicit ordering reduces silent mistakes that show up days later during review or signing.
Clean merges across A4 + Letter
Normalize sizes with fit/crop/keep behavior so printing and previews don't "jump."
Faster workflows
Merge on demand instead of manually assembling PDFs—and keep users moving forward.
One endpoint, many use cases
Onboarding packets, compliance bundles, reports—any time "these files must become one."
Less risk, more trust
A reliable merge is invisible—until it fails. Don't let document errors cost you approvals.
FAQ: Merge PDF API details people trip on
These are the questions that show up right after the first "it works on my machine" merge. Read them now and save yourself a future debugging session.
How does the order parameter work—and what if two inputs have the same order?
Each input gets an integer order. The API sorts inputs ascending and concatenates them into one output. If two inputs share the same value, treat that as a bug in your client logic—because the sequence becomes ambiguous.
Practical rule: assign 1..N based on your UI list position, not upload timestamps or filenames.
What should I do when merging A4 and Letter pages?
Decide based on the user's goal: printing or signing packets → use fit (avoid cropping), design fidelity → use crop, archival → use keep.
Most teams default to mode: "fit", target: "largest" so smaller pages don't look "zoomed" next to larger ones.
Is this the same as a "combine PDF API" or "concatenate PDF API"?
Yes—these terms are commonly used interchangeably. The core behavior is concatenation: append PDF B after PDF A, and so on. The difference is the production-grade controls: explicit ordering and clear page-size handling so the output is predictable.