Merge PDF API — Merge Any Number of PDFs in a Single Request
Every invoicing run, report cycle, and contract workflow ends the same way: a folder of separate PDFs that someone has to stitch together by hand. The Merge PDF API removes that step - send as many files as you need in a single REST request and get back one combined document, in exactly the order you provided. Fonts, images, and formatting come through untouched, and you can merge fresh uploads, previously stored files, or both in the same call. It's built for developers automating document pipelines - billing systems, report generators, contract assembly - who need a PDF merge REST API that runs unattended. Start free with 10,000 credits, no credit card required.
Features
No File-Count Limit
Send as many PDFs as you need in one call - the only ceiling is a 1GB total payload - and receive one merged document with deterministic page order. Pass stored files as a file_id array, attach uploads as multipart file fields, or mix both in the same request (uploads merge first, then IDs).
Use it to consolidate a month of generated invoices, or assemble multi-part reports, without batching logic on your side.
Merge Stored Files Without Re-Uploading
Every file you upload gets a reusable ID. Reference it through the file_id parameter in later merge calls instead of transferring the same bytes again - the response's inputIds array confirms every file that entered the merge.
Use it for template-driven assembly: upload your cover page and terms pages once, then merge them into every outgoing contract.
Asynchronous Processing
The API responds immediately with 200 OK and a unique taskId while the merge runs in the background, so your request thread never blocks on a large job. Poll the Task Status API with that taskId to track progress from queued to completed.
Use it to fold the PDF merging API into worker queues and scheduled jobs that can't sit on open connections.
Webhook Notifications
Skip polling entirely: pass a webhook_url and the API calls your endpoint the moment the task finishes. Secure the callback with a custom X-Webhook-Authorization header, and enable webhook_failure_notification to get an email to the requesting user or their organization admin if every webhook retry fails.
Use it to trigger the next pipeline stage - delivery, archiving, e-signing - with no schedulers.
Zero Data Retention on Request
Set destroy=true and your input files are permanently wiped from our servers the moment the merged output is generated. Leave it unset and files are retained up to 30 days depending on your plan, so you can re-merge or download without re-uploading.
Use it to keep compliance-sensitive documents - contracts, medical records, financial statements - off third-party storage.
No Quality Loss
The merge preserves the original documents byte-faithfully: fonts, embedded images, vector graphics, and layout carry into the output without compression or downsampling. The output parameter names the resulting file so downstream systems receive a predictable artifact.
Use it when the merged file is the deliverable - client-facing proposals, board packs, legal filings - and visual fidelity is non-negotiable.
Built for These Use Cases
Automated invoice and statement consolidation
Generate per-transaction PDFs all month, then merge each customer's set into one statement on a schedule. Because the API works as a combine PDF API for stored files, your billing job passes the accumulated file IDs in a single call and picks up the finished statement when the task completes - no temp directories, no manual assembly.
Contract and proposal assembly
Merge a stored cover page, the freshly generated agreement, and standard appendices into one ordered document as the final step of your document pipeline. Teams that would otherwise maintain a PDF merger API wrapper around a local library get the same result from one request, with the output ready for delivery or e-signature.
Compliance archiving with post-merge compression
Concatenate case files, audit evidence, or medical records into a single archival document, then hand the result to the PDF Compress API to shrink it before long-term storage. Merging programmatically keeps the archive's page order deterministic and reproducible.
Screenshot-to-report workflows
Capture pages as PDFs with the Website Screenshot API, then combine the captures into one monitoring or QA report - a two-call assemble PDF API workflow. It turns a folder of per-URL captures into a single reviewable document your team can diff run over run.
API Endpoint
Utility & Resource APIs
Use these endpoints to manage files and check task status.
Task Status API
task_id. The response includes creation and expiry timestamps to help you track result availability, along with specific error details if a task fails. Results are retained for up to 7 days, depending on the operation.File Status API
file_id. Returns details including file name, size, type, and creation/deletion timestamps. Generated or uploaded files are retained up to 30 days based on user's plan, unless destroy is enabled to delete them immediately. You can use this endpoint to check if the file has expired using its file_id.File Download API
PDF Delete API
Files List API
File Upload API
multipart/form-data request. Each file receives a unique file_id that can be used with the PDF APIs.Upload Binary API
file_id for uses with the PDF APIs.All Endpoints
| Endpoint | Description | Credits | Reference | Playground |
|---|---|---|---|---|
| Merge PDF | Combine multiple PDF files into one, instantly. | 200 | Reference | Playground |
How-To-Guides
Merging PDFs
Your pipeline just produced its last document of the batch - now you need one file to deliver. This walkthrough covers the full round trip on the PDF merge endpoint: submit the merge, track the task, and download the output. It uses the same three calls whether you upload files, reference stored IDs, or mix both.
Step 1: Upload and Merge PDFs
Kick off the merge by POSTing to /pdf/merge. Attach new files as multipart file fields and reference stored files with file_id query parameters - multipart uploads are merged first in the order they appear, followed by file IDs in their order. The response returns a taskId for tracking and an inputIds array confirming each file that entered the job.
# Standard Response { "taskId": "04a06cd5-158d-4191-a45b-6f58249c599d", "inputIds": [ "7a9e4b12-f3c8-4d56-b7e1-8c2f9d0a3e6f", "3f8d5c21-a4b7-4e69-9c1d-2e7f8a0b5c9d", "566dc743-d8fe-4943-8cef-61e5d3d6096c", "0d8371dc-734a-42b8-b941-64977fcf8183" ] } # Response with destroy=true (No File Ids as they are deleted right away) { "taskId": "04a06cd5-158d-4191-a45b-6f58249c599d" }curl -X POST "https://api.apifreaks.com/v1.0/pdf/merge?file_id=566dc743-d8fe-4943-8cef-61e5d3d6096c&file_id=0d8371dc-734a-42b8-b941-64977fcf8183&output=merged_document" \ -H "X-apikey : YOUR_API_KEY" \ -F "file=@/path/to/document1.pdf" \ -F "file=@/path/to/document2.pdf"
Notes:
- You can upload any number of PDF files (up to 1GB total payload size)
- Whether merging two files or a hundred, the Upload Binary API offers the most efficient way to upload large assets before processing
- All multipart files are processed first in the order they appear, then file IDs in their order
- In the response above, the first two IDs are from the uploaded files, the last two are the file IDs you provided
- Use the
destroy=trueparameter to delete input files after merge completes (returns onlytaskId) - File IDs must reference valid, active files stored on the API Freaks server. You can verify if a file is still available using the File Status API
Step 2: Check Task Status
A long merge shouldn't stall your worker, so the task runs in the background while you check in. Call /pdf/task-status with your taskId: a completed status carries outputUrls and outputFileId, a failed status carries error and message fields (for example, Invalid PDF File) so your retry logic knows whether to resubmit or drop the file. Note the expiresAt timestamp - download before it passes.
# Response (completed) { "taskId": "04a06cd5-158d-4191-a45b-6f58249c599d", "status": "completed", "createdAt": "2025-01-26 10:30:00", "outputUrls": [ "https://api.apifreaks.com/v1.0/pdf/resource/download?resource_id=9b2e7f3a-5c8d-4e1b-a6f9-0d3c8e7b2a5f" ], "outputFileId": [ "9b2e7f3a-5c8d-4e1b-a6f9-0d3c8e7b2a5f" ], "inputIds": [ "7a9e4b12-f3c8-4d56-b7e1-8c2f9d0a3e6f", "3f8d5c21-a4b7-4e69-9c1d-2e7f8a0b5c9d", "566dc743-d8fe-4943-8cef-61e5d3d6096c", "0d8371dc-734a-42b8-b941-64977fcf8183" ], "expiresAt": "2025-01-27 10:30:00" }curl -X GET "https://api.apifreaks.com/v1.0/pdf/task-status?task_id=04a06cd5-158d-4191-a45b-6f58249c599d" \ -H "X-apikey: YOUR_API_KEY"
# Response (failed) { "taskId": "04a06cd5-158d-4191-a45b-6f58249c599d", "status": "failed", "createdAt": "2025-01-26 10:30:00", "inputIds": [ "7a9e4b12-f3c8-4d56-b7e1-8c2f9d0a3e6f", "3f8d5c21-a4b7-4e69-9c1d-2e7f8a0b5c9d", "566dc743-d8fe-4943-8cef-61e5d3d6096c", "0d8371dc-734a-42b8-b941-64977fcf8183" ], "error": "Invalid PDF File", "message": "The provided file is not a valid PDF file.", "expiresAt": "2025-01-27 10:30:00" }curl -X GET "https://api.apifreaks.com/v1.0/pdf/task-status?task_id=04a06cd5-158d-4191-a45b-6f58249c599d" \ -H "X-apikey: YOUR_API_KEY"
Step 3: Download Merged PDF
Fetch the finished document from the outputUrls link via the File Download API, or store the outputFileId and feed it straight into another PDF operation - compress, protect, or split - without re-uploading.
curl -X GET "https://api.apifreaks.com/v1.0/pdf/resource/download?resource_id=9b2e7f3a-5c8d-4e1b-a6f9-0d3c8e7b2a5f" \ -H "X-apikey: YOUR_API_KEY" \ --output merged_document.pdf
Webhook Support
When the merge is one stage of a larger pipeline, polling wastes cycles - provide a webhook_url in the original request and let the API push the completion event to you instead.
Get automatic notifications when your task completes instead of polling the task status endpoint. Good for event-driven applications and real-time document processing.
Add webhook_url to your request. We'll send a POST request to this URL when the task finishes (either completed or failed).
See the Complete Webhook Example section below for a full demonstration including custom authorization headers.
Webhook Delivery
Webhook delivery will be attempted up to 3 times. If all retries fail and webhook_failure_notification is enabled, we'll send an email notification to the requesting user or their organization admin.
Custom Authorization Header
Use X-Webhook-Authorization to add a custom header to webhook requests for endpoint security.
Format: Key:Value
Example: If you send Authorization:Bearer token123, the webhook request will include: Authorization: Bearer token123
See the Complete Webhook Example below for a full demonstration.
Complete Webhook Example
Here's a complete example showing webhook integration with custom authorization header and failure notifications:
# Response { "taskId": "04a06cd5-158d-4191-a45b-6f58249c599d", "inputIds": [ "566dc743-d8fe-4943-8cef-61e5d3d6096c" ] }curl -X 'POST' \ 'https://api.apifreaks.com/v1.0/pdf/merge?webhook_url=https://yourdomain.com/webhook/pdf-merge&webhook_failure_notification=true' \ -H 'X-apiKey: YOUR_API_KEY' \ -H 'X-Webhook-Authorization: Authorization:Bearer token123' \ -F 'file=@/path/to/document.pdf'
Webhook Request Format
When your task completes, we send a POST request to your webhook_url with these headers:
| Header | Description |
|---|---|
Content-Type | Always application/json |
X-Signature | HMAC-SHA256 signature of the request body using your API key. Use this to verify the payload is authentic. |
| Custom Header | (If provided) Your custom header from X-Webhook-Authorization |
Webhook Response
The webhook payload contains the same response structure as the Task Status API endpoint when checked for the task ID.
Note: TheinputIds field is excluded from the webhook response when the destroy parameter is set to true in the original request.Verifying Webhook Authenticity
Use the X-Signature header to verify webhook requests actually came from API Freaks and weren't tampered with.
How the signature works:
- We compute an HMAC-SHA256 hash of the request body using your API key as the secret
- We Base64-encode the result
- We send this as the
X-Signatureheader value
To verify the webhook:
- Take the raw payload body (JSON string exactly as received without parsing it)
- Compute HMAC-SHA256 of the payload using your API key as the secret
- Base64-encode the result of the hash
- Compare with the
X-Signatureheader value
Important: Don't transform or process the raw request body before verification. Adding whitespace or other formatting creates a different signature and verification will fail.
Frequently Asked Questions
taskId immediately. Poll the Task Status API until status is completed, then download from the outputUrls link or reuse the outputFileId in another PDF API call. If you passed a webhook_url, the completion payload is pushed to your endpoint instead.Pricing
To use this API, API credits are required. Charges apply only for successful queries, defined by a 2xx status code. If a request results in a 4xx or 5xx status code, no credits will be deducted, and any credits already charged will be refunded. In the event of a Task Processing Error, a maximum of 200 credits will be refunded. Surcharges for additional file sizes are non-refundable.
For each successful request, 200 credits will be charged. 1 extra credit will be charged per MB beyond 50 MB.
Utilize the Credits Usage API to efficiently monitor your recent consumption of both one-off and subscription credits. This API provides a streamlined way to track and manage your credit usage, ensuring you stay informed about your remaining balance and can optimize your resource allocation effectively.