Skip to main content
This tool requires publicly accessible PDF URLs. If your files are stored locally or in memory, you can upload them to our temporary bucket first using the Get Signed Upload URL endpoint.
POST https://api.pdfnoodle.com/v1/tools/merge-pdfs

​
Request

curl --location 'https://api.pdfnoodle.com/v1/tools/merge-pdfs' \
--header 'Authorization: Bearer pdfnoodle_api_123456789' \
--header 'Content-Type: application/json' \
--data '{
    "urls": [
        "https://example.com/document-1.pdf",
        "https://example.com/document-2.pdf",
        "https://example.com/document-3.pdf"
    ],
    "finalFilename": "merged-report.pdf",
    "expiration": 3600
}'

​
Response

{
  "status": "SUCCESS",
  "url": "https://s3.amazonaws.com/...",
  "fileName": "merged-report.pdf",
  "urlValidUntil": "2025-01-01T02:00:00.000Z"
}
The response contains a url pointing to the merged PDF file. While the URL in the response expires after the time specified in expiration (default: 1 hour), the file itself is stored persistently and can be downloaded at any time from the dashboard logs.
PDFs are merged in the exact order they appear in the urls array. Make sure to order them correctly.

​
Operation Tracking

Each merge operation creates a record in your dashboard logs, allowing you to:
  • View all past merge operations with their status and metadata
  • Re-download merged files at any time via the logs table
  • Track usage across your team
Business and Scale plans: Merge operations are unlimited and do not count toward your PDF generation quota.Starter plans: Merge operations count toward your total volume quota.

​
Async Mode

By default, the request waits for the merge to complete before returning a response. If you set async: true, the endpoint returns immediately with a requestId and statusUrl that you can use to poll for the result.
Async Response (200 OK)
{
  "requestId": "pdfnoodle_request_123456789",
  "statusUrl": "https://api.pdfnoodle.com/v1/tools/status/pdfnoodle_request_123456789",
  "message": "The tool is being executed asynchronously. Check the status using the status URL."
}
Use the Get Tool Status endpoint to check the result.

​
Request Timeout (>30 seconds)

Even without async: true, if the operation takes more than 30 seconds it will automatically be processed in the background.
If the merge takes longer than 30 seconds, you’ll receive a 202 Accepted response with a requestId and statusUrl to poll for the result:
Timeout (202 Accepted)
{
  "requestId": "pdfnoodle_request_123456789",
  "statusUrl": "https://api.pdfnoodle.com/v1/tools/status/pdfnoodle_request_123456789",
  "message": "Couldn't complete the operation within 30 seconds, it is being processed asynchronously. Check the status using the status URL."
}

​
Parameters

​
urls
string[]
required
An array of URLs pointing to the PDF files you want to merge. A minimum of 2 URLs is required. Each URL must be a valid, publicly accessible URL.
​
finalFilename
string
The desired filename for the merged PDF. Must end with .pdf. If not provided, a random filename will be generated.
​
expiration
number
default:"3600"
Number of seconds that the generated signed URL will take to expire. Must be between 60 (1 minute) and 604800 (7 days). Default: 3600 (1 hour).
​
async
boolean
default:"false"
If true, the request returns immediately with a requestId and statusUrl instead of waiting for the operation to complete. You can then poll the Get Tool Status endpoint to check when the result is ready.