Inkspan › Guides › How to merge PDF files in cURL

How to merge PDF files in cURL

Combining several PDFs into one is the kind of task that looks trivial until you are handling encrypted inputs, mismatched page sizes, and malformed files from users. The /v1/pdf/merge endpoint accepts any number of PDFs in a single multipart request and returns them concatenated in the order you sent them.

Typical uses are stitching a cover page onto a generated report, assembling an appendix, or batching per-customer documents into one file for printing.

Also in: Python · Node.js

cURL example

curl -X POST https://api.inkspan.dev/v1/pdf/merge \
  -H "X-API-Key: ink_live_..." \
  -F "files=@first.pdf" \
  -F "files=@second.pdf" \
  --output merged.pdf

Request parameters

Name	Type	Required	Description
`files`	file[]	yes	Two or more PDF files. Repeat the `files` field once per document — do not send an array in a single field.

Response

Returns a PDF as a binary stream with Content-Type: application/pdf and Content-Disposition: attachment; filename=merged.pdf. Write the response body straight to disk — do not parse it as JSON.

Things that catch people out

The field is repeated, not indexed. Send files twice rather than files[0] and files[1]; a single file returns a copy rather than an error.
Order is the order of the parts in your request, so control it client-side if it matters.
Page sizes are preserved per page. Merging A4 and Letter gives a mixed-size PDF rather than normalising either.
Password-protected inputs fail to parse. Decrypt before merging.

Errors

Status	Meaning	Fix
`401`	Invalid or missing API key	Send your key in the `X-API-Key` header.
`402`	Monthly quota exceeded	The response reports used/quota. Upgrade at inkspan.dev/#pricing.
`422`	Missing or invalid parameter	Check required fields in the table above — the body names the offending field.

Failed requests do not count against your quota; only successful ones are metered.

Frequently asked questions

How many files can I merge at once?

There is no fixed count limit; the practical ceiling is total request size. For very large batches, merge in groups and then merge the results.

Does merging count as one document against my quota?

Yes — quota is metered per successful request, so one merge call is one document regardless of how many files it combines.

Are bookmarks and form fields preserved?

Page content is preserved. Document-level structures such as bookmarks and AcroForm fields may not survive concatenation; flatten forms first with /v1/pdf/fill-form if you need the values baked in.

Get a free API key →

Related Manipulate guides: split a PDF into pages · compress a PDF · add a watermark to a PDF · convert a PDF to images · fill a PDF form