Batch Request

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

array

required

An array of HTML to PDF conversion items. Minimum 1 item, maximum 20 items per batch.Each item accepts the following properties:

Show Item properties

string

required

The HTML content you want to render

object

The object containing the parameters for your PDF. See all the options here.

boolean

default:"false"

If true, will return a .PNG file instead of a .PDF file

string

The id of the active s3 connection you want to store your generated file on. (only available in the high plan)

string

The path, including subdirectories and the filename without extension, to use when saving the render in your S3 bucket. (only available if being stored in custom s3_bucket)

object

This object containing the metadata for your PDF. See all the options here.

boolean

default:"false"

If true, will hide the footer and the header elements on the first page of the generated PDF

boolean

default:"false"

If true, will enter Debug Mode and show additional properties on the response to help you figure out your variables and html rendered content. Here’s everything you need to know about Debug Mode

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.

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.

string

A URL to receive a POST request when the batch is complete. The webhook payload will contain the full batch status and results.

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.

Getting Started

Generate PDF from Template

Convert HTML to PDF

PDFs

Templates

Options

Guides

Request

Response

Merged Response

Parameters

Async Mode

Payload Size Limit

Checking Batch Status

​Request

​Response

​Merged Response

​Parameters

​Async Mode

​Payload Size Limit

​Checking Batch Status

Request

Response

Merged Response

Parameters

Async Mode

Payload Size Limit

Checking Batch Status