--- title: "PDF merge API" canonical_url: "https://www.nutrient.io/guides/dws-processor/tools-and-api/pdf-merge-api/" md_url: "https://www.nutrient.io/guides/dws-processor/tools-and-api/pdf-merge-api.md" last_updated: "2026-07-06T00:00:00.000Z" description: "Merge multiple PDF files into a single PDF using Nutrient DWS Processor API. Combine complete documents or selected page ranges in the order you specify." --- # PDF merge API Use the PDF merge API to combine multiple PDF documents into a single output file. The [`/build` endpoint](https://www.nutrient.io/api/reference/public/#tag/Document-Editing/operation/build-document) handles the merge operation. Add each input PDF as a `parts` item, and Nutrient DWS Processor API assembles the output in the same order. For signup, pricing, and task-level examples, refer to the [merge PDF API task page](https://www.nutrient.io/api/merge-pdf-api/). ## Merge multiple PDFs The following example merges two PDF files, `first_half.pdf` and `second_half.pdf`, into a single `result.pdf`. The order of the `parts` array controls the order of the documents in the merged PDF: ### Shell ### Shell (Windows) ### Java ### C# ### JavaScript ### Python ### PHP ### HTTP ## Merge PDFs from URLs For remotely hosted source files, send a JSON request and pass each file URL in `parts[].file.url`. Use this instructions object: ```json { "parts": [ { "file": { "url": "https://example.com/cover.pdf" } }, { "file": { "url": "https://example.com/body.pdf" } }, { "file": { "url": "https://example.com/appendix.pdf" } } ] } ``` ### Shell Run this request to merge PDFs from URLs: ```bash curl -X POST https://api.nutrient.io/build \ -H "Authorization: Bearer $NUTRIENT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "parts": [ { "file": { "url": "https://example.com/cover.pdf" } }, { "file": { "url": "https://example.com/body.pdf" } }, { "file": { "url": "https://example.com/appendix.pdf" } } ] }' \ -o result.pdf ``` ## Merge selected page ranges You can merge selected pages from one or more source PDFs by adding a `pages` object to a part. Page indexes are zero-based, and negative numbers count from the end of the document. For example, `0` is the first page, and `-1` is the last page. The following example creates a packet from the first three pages of `document.pdf`, followed by the full `appendix.pdf` file: ```json { "parts": [ { "file": "document", "pages": { "start": 0, "end": 2 } }, { "file": "appendix" } ] } ``` ## Reorder pages while merging You can reference the same input file more than once to reorder or duplicate page ranges in the output. The following example places the last page first, followed by the rest of the document: ```json { "parts": [ { "file": "document", "pages": { "start": -1, "end": -1 } }, { "file": "document", "pages": { "start": 0, "end": -2 } } ] } ``` ## Merge password-protected PDFs If an input PDF is password-protected, include the password on the corresponding part. Use this instructions object: ```json { "parts": [ { "file": "protected_document", "password": "document-password" }, { "file": "appendix" } ] } ``` Nutrient DWS Processor API uses passwords only to open source documents for processing. To set a password on the merged output, configure `output.user_password`, `output.owner_password`, and `output.user_permissions`. ## Combine merging with other actions The `/build` endpoint can merge documents and then apply additional actions to the assembled PDF. Actions run after Nutrient DWS Processor API combines the `parts`. The following example merges two PDFs and then adds a watermark to the merged output: ```json { "parts": [ { "file": "first_half" }, { "file": "second_half" } ], "actions": [ { "type": "watermark", "text": "CONFIDENTIAL", "width": "50%", "height": "20%", "opacity": 0.3, "rotation": 45 } ] } ``` For workflows that include signing, apply all merge, page-range, rotation, watermarking, and flattening operations before signing the final PDF. ## Reference A PDF merge request uses the Build API `parts` array. Each part represents an input document or a selected page range from an input document: ```typescript type FilePart = { // Multipart field name, or a remote URL object. file: string | { url: string }, // Optional password for encrypted input PDFs. password?: string, // Optional page range. Page indexes are zero-based. // Negative values count from the end of the document. pages?: { start?: number, end?: number, }, }; type BuildInstructions = { parts: FilePart[], actions?: BuildAction[], output?: { type?: "pdf", }, }; ``` ## Related API reference operations - Refer to the [build document endpoint](https://www.nutrient.io/api/reference/public/#tag/Document-Editing/operation/build-document) API reference for merging PDFs, selecting page ranges, and applying follow-up actions in a single request. ## Related guides - Refer to the [PDF split API](https://www.nutrient.io/guides/dws-processor/tools-and-api/pdf-split-api.md) guide. - Refer to the [PDF rotate API](https://www.nutrient.io/guides/dws-processor/tools-and-api/pdf-rotate-api.md) guide. - Refer to the [PDF flatten API](https://www.nutrient.io/guides/dws-processor/tools-and-api/pdf-flatten-api.md) guide. - Refer to the [PDF watermark API](https://www.nutrient.io/guides/dws-processor/tools-and-api/pdf-watermark-api.md) guide. - Refer to the [PDF security API](https://www.nutrient.io/guides/dws-processor/tools-and-api/pdf-security-api.md) guide. - Refer to the [tools and APIs](https://www.nutrient.io/guides/dws-processor/tools-and-api.md) guide. --- ## Related pages - [Image-to-PDF API](/guides/dws-processor/tools-and-api/image-to-pdf-api.md) - [Analyze Build API](/guides/dws-processor/tools-and-api/analyze-build-api.md) - [Tools and APIs](/guides/dws-processor/tools-and-api.md) - [Document-to-image API](/guides/dws-processor/tools-and-api/document-to-image-api.md) - [Import Instant JSON API](/guides/dws-processor/tools-and-api/import-instant-json-api.md) - [DOCX templating API](/guides/dws-processor/tools-and-api/docx-templating-api.md) - [Import XFDF annotations API](/guides/dws-processor/tools-and-api/import-xfdf-annotations-api.md) - [Office-to-PDF API](/guides/dws-processor/tools-and-api/office-to-pdf-api.md) - [Markdown-to-PDF API](/guides/dws-processor/tools-and-api/markdown-to-pdf-api.md) - [PDF digital signature API](/guides/dws-processor/tools-and-api/pdf-digital-signature-api.md) - [PDF form filling API](/guides/dws-processor/tools-and-api/pdf-form-filling-api.md) - [PDF flatten API](/guides/dws-processor/tools-and-api/pdf-flatten-api.md) - [PDF OCR API](/guides/dws-processor/tools-and-api/pdf-ocr-api.md) - [PDF generator API](/guides/dws-processor/tools-and-api/pdf-generator-api.md) - [PDF linearization API](/guides/dws-processor/tools-and-api/pdf-linearization-api.md) - [PDF rotate API](/guides/dws-processor/tools-and-api/pdf-rotate-api.md) - [PDF optimization API](/guides/dws-processor/tools-and-api/pdf-optimization-api.md) - [PDF security API](/guides/dws-processor/tools-and-api/pdf-security-api.md) - [PDF page manipulation API](/guides/dws-processor/tools-and-api/pdf-page-manipulation-api.md) - [PDF split API](/guides/dws-processor/tools-and-api/pdf-split-api.md) - [PDF-to-HTML API](/guides/dws-processor/tools-and-api/pdf-to-html-api.md) - [PDF-to-image API](/guides/dws-processor/tools-and-api/pdf-to-image-api.md) - [PDF-to-Markdown API](/guides/dws-processor/tools-and-api/pdf-to-markdown-api.md) - [PDF-to-Office API](/guides/dws-processor/tools-and-api/pdf-to-office-api.md) - [PDF-to-PDF/A API](/guides/dws-processor/tools-and-api/pdf-to-pdfa-api.md) - [PDF watermark API](/guides/dws-processor/tools-and-api/pdf-watermark-api.md) - [Redaction API](/guides/dws-processor/tools-and-api/redaction-api.md) - [PDF/UA auto-tagging API](/guides/dws-processor/tools-and-api/pdfua-api.md)