Merge Multiple PDF Files

PDF4me Merge is a REST endpoint that combines multiple PDFs into a single document. POST an array of Base64-encoded files to /api/v2/Merge with an output name, and the API appends them in array order and returns the merged PDF as raw bytes. Set async true for large batches and poll the Location URL until the result is ready.

What this endpoint does

Takes two or more PDFs and returns one: invoice plus attachments, cover page plus report, a folder of scans consolidated into a single file. The array order is the page order, so your code fully controls the result. This is the plain concatenation endpoint; overlaying pages on top of each other is a separate action (Merge Overlay).

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

POST/api/v2/Merge

Postman URLhttps://api.pdf4me.com/api/v2/Merge

Important Facts You Should Not Miss

docContent is an array, and order matters

Unlike most PDF4me endpoints where docContent is a single string, here it is an ARRAY of Base64 strings. The array order is the merge order; there is no separate ordering parameter.

A 200 response is the PDF itself

The body is raw binary, not a JSON wrapper. Write the bytes straight to a .pdf file. JSON-parsing the response or Base64-decoding it corrupts the output.

async true for big batches

With "async": true the API answers 202 Accepted with a Location header. Poll it with GET about every 10 seconds (the official samples use 10s intervals, up to 20 retries) until 200 returns the merged file.

HTTP setup

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

A 200 response body is the merged PDF as raw bytes: save it directly. A 202 response means the merge is running asynchronously: poll the Location URL until 200.

How do sync and async processing differ?

The async flag changes the response contract, not the merge result. Pick by batch size.

Sync vs async	`"async": false` (default)	`"async": true`
Response on success	200 with the merged PDF as raw bytes	202 Accepted with a `Location` polling URL
Connection	Held open until the merge finishes	Returns immediately
How to get the file	Save the response body directly	GET the Location URL every ~10 seconds until it answers 200 with the bytes
Best for	A few small files	Large batches and big documents

API body fields

Parameter	Required	Type	What it does	Example
`docContent`	Required	array of strings	An array of Base64-encoded PDF files, at least two entries. The array order is the merge order of the output document.	`["JVBERi0x...", "JVBERi0x..."]`
`docName`	Required	string	Output filename for the merged PDF.	`merged.pdf`
`async`	Optional	boolean	false (default) returns the merged PDF directly on 200. true returns 202 plus a Location URL to poll, for large batches.	`true`

Sample payloads

Merge two PDFs synchronously

{
 "docContent": [
 "JVBERi0xLjcKJb...first PDF Base64...",
 "JVBERi0xLjcKJb...second PDF Base64..."
 ],
 "docName": "merged.pdf"
}

Merge a large batch asynchronously

{
 "docContent": [
 "JVBERi0x...cover...",
 "JVBERi0x...report...",
 "JVBERi0x...appendix-a...",
 "JVBERi0x...appendix-b..."
 ],
 "docName": "quarterly-pack.pdf",
 "async": true
}

Postman collection tips

Headers

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

Body

raw JSON. docContent is an ARRAY of Base64 strings, one per source PDF, in merge order.

Response

On 200, switch Postman to "Send and Download": the body is the PDF itself, not JSON.

Async

With async true, copy the Location header from the 202 response into a GET request and poll it until 200.

curl example

curl -X POST https://api.pdf4me.com/api/v2/Merge \
 -H "Content-Type: application/json" \
 -H "Authorization: Basic YOUR_API_KEY" \
 -d '{
 "docContent": [
 "'"$(base64 -w 0 first.pdf)"'",
 "'"$(base64 -w 0 second.pdf)"'"
 ],
 "docName": "merged.pdf"
 }' \
 --output merged.pdf

What does the API return?

Field	Type	What it contains
`200 response body`	Binary (application/pdf)	The merged PDF file itself as raw bytes. Save it directly to disk; do not JSON-parse or Base64-decode.
`202 Location header`	URL	Async mode only: the polling URL. GET it about every 10 seconds until it returns 200 with the merged PDF bytes.
`4xx/5xx response body`	JSON or text	Error details: 400 for malformed Base64 or a bad payload shape, 401 for a missing or invalid API key, 500 for server-side processing failures.

Code samples

Official, runnable samples for this exact endpoint, per language:

FAQ

How is the merge order decided?+

By the docContent array order. The first Base64 string becomes the first pages of the output, the second is appended after it, and so on. Reorder the array to reorder the merged document.

Is the response JSON with a Base64 file inside?+

No. A 200 response body is the merged PDF itself as raw binary bytes. Write response.content straight to a .pdf file; do not JSON-parse or Base64-decode it.

When should I set async to true?+

For large batches or big files. With async true the API returns 202 Accepted plus a Location header; poll that URL with GET requests about every 10 seconds until it returns 200 with the merged PDF.

Can I merge Word or Excel files with this endpoint?+

No. /api/v2/Merge accepts PDFs only. Merge Word files with the Merge Documents Word endpoint, or convert other formats to PDF first and then merge the results here.

How many PDFs can I merge in one call?+

The docContent array accepts multiple documents in a single request; two entries is the minimum meaningful merge. For very large batches, set async true so the merge runs server-side while you poll for the result.

What is the difference between Merge and Merge Overlay?+

Merge appends documents one after another, page by page. Merge Overlay stamps the pages of one PDF on top of the pages of another, which is what you want for letterheads and backgrounds.

Why am I getting a 400 Bad Request?+

The usual causes are a docContent that is a single string instead of an array, an entry that is not valid Base64, or a source file that is not actually a PDF. Encode each file separately and keep the array shape.

Why merge PDFs via API instead of a desktop tool?

Desktop and web merge tools are fine for one-off jobs, but they need a human to select files, drag them into order, and download the result. The API does the same concatenation as one deterministic request per batch, with the order fixed by your code rather than by drag-and-drop. The output is a standard PDF conforming to the ISO 32000 specification, so it opens in any reader and feeds cleanly into the next pipeline step, whether that is compression, OCR, or e-signing.

Merge PDF Overlay

Stamp one PDF on top of another instead of appending pages.

Split PDF

The inverse operation: break one PDF into separate documents.

Merge Word Documents

Combining .docx files instead of PDFs uses the Word merge endpoint.