Skip to main content

Merge PDFs

Merges multiple PDF files into a single PDF file.

This endpoint accepts PDF files in the multipart/form-data request and combines them in alphanumeric order (numbers first, then alphabetical).

Basics​

POST/forms/pdfengines/merge
Headers
Gotenberg-Output-Filenamestring
The filename of the resulting file - Gotenberg automatically appends the file extension. Defaults to a random UUID filename.
Gotenberg-Tracestring
A custom request ID to identify the request in the logs; overrides the default UUID.
Form Files
filesfile[]required
PDF files to merge.
Example Request
cURL
curl \
--request POST http://localhost:3000/forms/pdfengines/merge \
--form files=@/path/to/1_pdf.pdf \
--form files=@/path/to/2_pdf.pdf \
--form files=@/path/to/3_pdf.pdf \
-o my.pdf
Responses
The merged PDF file.
Content-Disposition: attachment; filename={output-filename.pdf}
Content-Type: {content-type}
Content-Length: {content-length}
Gotenberg-Trace: {trace}
Body: {output-file}

Structure & Metadata​

Form Fields
metadatajson
Writes metadata (Author, Title, etc.).
Default:None
flattenboolean
Converts form fields into static content, preventing further editing.
Default:false
Form Files
embedsfile[]
Embeds files into the PDF.
Default:None

Metadata (PDF Engines)​

Use the metadata form field to inject XMP metadata into the generated PDF. This allows you to set properties like Author, Title, Copyright, and Keywords by passing a JSON-formatted object.

Valid Keys

Not all metadata tags are writable. Gotenberg relies on ExifTool for this operation. See the XMP Tag Name documentation for a list of potential keys.

Compliance Warning

Writing metadata involves modifying the PDF structure and usually breaks PDF/A compliance.

Example Request
cURL
curl \
--request POST http://localhost:3000/forms/pdfengines/merge \
--form files=@/path/to/1_pdf.pdf \
--form files=@/path/to/2_pdf.pdf \
--form files=@/path/to/3_pdf.pdf \
--form 'metadata={"Author":"Julien Neuhart","Copyright":"Julien Neuhart","CreationDate":"2006-09-18T16:27:50-04:00","Creator":"Gotenberg","Keywords":["first","second"],"Marked":true,"ModDate":"2006-09-18T16:27:50-04:00","PDFVersion":1.7,"Producer":"Gotenberg","Subject":"Sample","Title":"Sample","Trapped":"Unknown"}' \
-o my.pdf

Attachments (PDF Engines)​

Use the embeds form field to attach external files directly inside the PDF container.

Common Use Case: This is essential for e-invoicing standards like ZUGFeRD / Factur-X, which require a human-readable PDF to carry a machine-readable XML invoice as an attachment.

Example Request
cURL
curl \
--request POST http://localhost:3000/forms/pdfengines/merge \
--form files=@/path/to/1_pdf.pdf \
--form files=@/path/to/2_pdf.pdf \
--form files=@/path/to/3_pdf.pdf \
--form embeds=@invoice.xml \
--form embeds=@logo.png \
-o my.pdf

Flatten (PDF Engines)​

Use the flatten form field to make the PDF non-interactive.

This process merges all interactive form fields (text inputs, checkboxes, etc.) directly into the page content. The resulting PDF cannot be modified by the end-user.

Example Request
cURL
curl \
--request POST http://localhost:3000/forms/pdfengines/merge \
--form files=@/path/to/1_pdf.pdf \
--form files=@/path/to/2_pdf.pdf \
--form files=@/path/to/3_pdf.pdf \
--form flatten=true \
-o my.pdf

PDF/A & PDF/UA (PDF Engines)​

Use the pdfa and pdfua form fields to convert the result into a standardized PDF format during post-processing.

  • Process: Gotenberg generates the result, then re-processes it using LibreOffice (the only engine supporting these standards).
  • Performance: Slower (requires a second conversion pass).
  • Result: A compliant PDF/A (Archival) or PDF/UA (Universal Accessibility) document.
Form Fields
pdfaenum
Converts to a specific PDF/A archival standard. Options: 'PDF/A-1b', 'PDF/A-2b', 'PDF/A-3b'.
pdfuaboolean
Enables PDF/UA (Universal Accessibility) compliance.
Default:false
Example Request
cURL
curl \
--request POST http://localhost:3000/forms/pdfengines/merge \
--form files=@/path/to/1_pdf.pdf \
--form files=@/path/to/2_pdf.pdf \
--form files=@/path/to/3_pdf.pdf \
--form userPassword=my_user_password \
--form ownerPassword=my_owner_password \
-o my.pdf

Encryption (PDF Engines)​

Secure your PDF by setting passwords that control access and permissions.

  • User Password: Required to open and view the PDF.
  • Owner Password: Required to modify permissions (e.g., printing, copying text, extracting pages).
PDF Engine Dependency

The encryption strength (e.g., AES-256) depends on the configured PDF Engine (QPDF, pdfcpu, or PDFtk).

Check the PDF Engines Configuration to see which engine is active.

Form Fields
userPasswordstring
The password required to open the PDF.
Default:None
ownerPasswordstring
The password required to change permissions or edit the PDF.
Default:None
Example Request
cURL
curl \
--request POST http://localhost:3000/forms/pdfengines/merge \
--form files=@/path/to/1_pdf.pdf \
--form files=@/path/to/2_pdf.pdf \
--form files=@/path/to/3_pdf.pdf \
--form userPassword=my_user_password \
--form ownerPassword=my_owner_password \
-o my.pdf
TheCodingMachinepdfme
Powered by
DockerJetBrains
❤️ Become a sponsor