Skip to main content
Batch HTML to PDF allows you to convert up to 20 HTML documents into PDFs in a single API call. You can also merge all generated PDFs into a single file.
POST https://api.pdfnoodle.com/v1/html-to-pdf/batch

​
Request

curl --location 'https://api.pdfnoodle.com/v1/html-to-pdf/batch' \
--header 'Authorization: Bearer pdfnoodle_api_123456789' \
--header 'Content-Type: application/json' \
--data '{
    "items": [
        {
            "html": "<html><body><h1>Invoice #001</h1><p>Total: $150.00</p></body></html>"
        },
        {
            "html": "<html><body><h1>Invoice #002</h1><p>Total: $250.00</p></body></html>"
        }
    ],
    "merge": false
}'

const response = await fetch("https://api.pdfnoodle.com/v1/html-to-pdf/batch", {
  method: "POST",
  headers: {
    Authorization: "Bearer pdfnoodle_api_123456789",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    items: [
      {
        html: "<html><body><h1>Invoice #001</h1><p>Total: $150.00</p></body></html>",
      },
      {
        html: "<html><body><h1>Invoice #002</h1><p>Total: $250.00</p></body></html>",
      },
    ],
    merge: false,
  }),
});

const result = await response.json();

import requests

response = requests.post(
    'https://api.pdfnoodle.com/v1/html-to-pdf/batch',
    headers={
        'Authorization': 'Bearer pdfnoodle_api_123456789',
        'Content-Type': 'application/json'
    },
    json={
        'items': [
            {
                'html': '<html><body><h1>Invoice #001</h1><p>Total: $150.00</p></body></html>'
            },
            {
                'html': '<html><body><h1>Invoice #002</h1><p>Total: $250.00</p></body></html>'
            }
        ],
        'merge': False
    }
)

result = response.json()

​
Response

By default, the request waits for all PDFs to be generated before returning a response (synchronous behavior). If the batch takes longer than 30 seconds, it will return a 202 Accepted response with a status URL to poll. 
{
  "batchRequestId": "pdfnoodle_batch_123456789",
  "status": "SUCCESS",
  "total": 2,
  "completed": 2,
  "merge": false,
  "results": [
    {
      "requestId": "pdfnoodle_request_abc123",
      "renderStatus": "SUCCESS",
      "signedUrl": "https://pdforge-production.s3.us-east-2.amazonaws.com/...",
      "metadata": {
        "executionTime": "1.805 seconds",
        "fileSize": "4.066 kB"
      }
    },
    {
      "requestId": "pdfnoodle_request_def456",
      "renderStatus": "SUCCESS",
      "signedUrl": "https://pdforge-production.s3.us-east-2.amazonaws.com/...",
      "metadata": {
        "executionTime": "2.103 seconds",
        "fileSize": "5.200 kB"
      }
    }
  ]
}

{
  "batchRequestId": "pdfnoodle_batch_123456789",
  "status": "PARTIAL_SUCCESS",
  "total": 2,
  "completed": 2,
  "merge": false,
  "results": [
    {
      "requestId": "pdfnoodle_request_abc123",
      "renderStatus": "SUCCESS",
      "signedUrl": "https://pdforge-production.s3.us-east-2.amazonaws.com/...",
      "metadata": {
        "executionTime": "1.805 seconds",
        "fileSize": "4.066 kB"
      }
    },
    {
      "requestId": "pdfnoodle_request_def456",
      "renderStatus": "FAILED",
      "signedUrl": "",
      "metadata": {}
    }
  ]
}

{
  "batchRequestId": "pdfnoodle_batch_123456789",
  "statusUrl": "https://api.pdfnoodle.com/v1/pdf/batch/status/pdfnoodle_batch_123456789",
  "message": "Batch couldn't complete within 30 seconds. Check the batch status URL for progress."
}
The status field indicates the overall outcome of the batch:
  • SUCCESS - All PDFs were generated successfully
  • PARTIAL_SUCCESS - Some PDFs were generated, but at least one failed
  • FAILED - All PDFs failed to generate

​
Merged Response

When merge is set to true, the response will also include a mergedUrl pointing to a single PDF containing all successfully generated PDFs combined: 
{
  "batchRequestId": "pdfnoodle_batch_123456789",
  "status": "SUCCESS",
  "total": 2,
  "completed": 2,
  "merge": true,
  "mergedUrl": "https://pdforge-production.s3.us-east-2.amazonaws.com/merged/...",
  "results": [...]
}

​
Parameters

​
items
array
required
An array of HTML to PDF conversion items. Minimum 1 item, maximum 20 items per batch.Each item accepts the following properties:
​
async
boolean
default:"false"
If true, the request will return immediately with a batchRequestId and statusUrl. You can poll the Get Batch PDF Status endpoint to track progress.
​
merge
boolean
default:"false"
If true, all successfully generated PDFs will be merged into a single file. The merged file URL will be available in the mergedUrl field of the response. Cannot be used when any item has convertToImage set to true.
​
webhook
string
A URL to receive a POST request when the batch is complete. The webhook payload will contain the full batch status and results.
​
signedUrlExpiresIn
number
default:"3600"
Number of seconds that the generated signed URLs will take to expire (default: 1 hour)

​
Async Mode

When async is set to true, the request returns immediately with a batchRequestId and a statusUrl: 
{
  "batchRequestId": "pdfnoodle_batch_123456789",
  "statusUrl": "https://api.pdfnoodle.com/v1/pdf/batch/status/pdfnoodle_batch_123456789",
  "total": 2,
  "subRequestIds": ["pdfnoodle_request_abc123", "pdfnoodle_request_def456"],
  "message": "Batch PDF generation started. Check the status URL for progress."
}
You can then check the status of your batch using the Get Batch PDF Status endpoint.

​
Payload Size Limit

The request body is limited to 3MB. Since batch requests contain multiple items with raw HTML content, this limit can be reached quickly when sending many items with large HTML documents. If your request exceeds this limit, you’ll receive a 413 status code with the following error: 
{
  "message": "request entity too large"
}
If you’re hitting the 3MB payload limit, consider splitting your batch into multiple smaller requests. For example, instead of sending 20 items in a single request, send two requests with 10 items each.

​
Checking Batch Status

You can check the status of your batch at any time using the Get Batch PDF Status endpoint with the batchRequestId. To check the status of an individual PDF within the batch, use the Get PDF Status endpoint with the individual requestId from the results.