> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pdfnoodle.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Batch Request
> Generate multiple PDFs from templates in a single request. Process up to 20 PDFs at once, with optional merging into a single file.
Batch PDF generation allows you to generate up to 20 PDFs in a single API call.
Each item in the batch can use a different template and data. You can also merge all generated PDFs into a single file.
POST [https://api.pdfnoodle.com/v1/pdf/batch](https://api.pdfnoodle.com/v1/pdf/batch)
## Request
```bash cURL theme={null}
curl --location 'https://api.pdfnoodle.com/v1/pdf/batch' \
--header 'Authorization: Bearer pdfnoodle_api_123456789' \
--header 'Content-Type: application/json' \
--data '{
"items": [
{
"templateId": "invoice",
"data": {
"invoiceNumber": "INV-001",
"customer": { "name": "John Doe" },
"total": "$150.00"
}
},
{
"templateId": "invoice",
"data": {
"invoiceNumber": "INV-002",
"customer": { "name": "Jane Smith" },
"total": "$250.00"
}
}
],
"merge": false
}'
```
```javascript JavaScript theme={null}
const response = await fetch("https://api.pdfnoodle.com/v1/pdf/batch", {
method: "POST",
headers: {
Authorization: "Bearer pdfnoodle_api_123456789",
"Content-Type": "application/json",
},
body: JSON.stringify({
items: [
{
templateId: "invoice",
data: {
invoiceNumber: "INV-001",
customer: { name: "John Doe" },
total: "$150.00",
},
},
{
templateId: "invoice",
data: {
invoiceNumber: "INV-002",
customer: { name: "Jane Smith" },
total: "$250.00",
},
},
],
merge: false,
}),
});
const result = await response.json();
```
```python Python theme={null}
import requests
response = requests.post(
'https://api.pdfnoodle.com/v1/pdf/batch',
headers={
'Authorization': 'Bearer pdfnoodle_api_123456789',
'Content-Type': 'application/json'
},
json={
'items': [
{
'templateId': 'invoice',
'data': {
'invoiceNumber': 'INV-001',
'customer': {'name': 'John Doe'},
'total': '$150.00'
}
},
{
'templateId': 'invoice',
'data': {
'invoiceNumber': 'INV-002',
'customer': {'name': 'Jane Smith'},
'total': '$250.00'
}
}
],
'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.
```json Success (200 OK) theme={null}
{
"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"
}
}
]
}
```
```json Partial Success (200 OK) theme={null}
{
"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": {}
}
]
}
```
```json Timeout (202 Accepted) theme={null}
{
"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:
```json theme={null}
{
"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
An array of PDF generation items. Minimum 1 item, maximum 20 items per batch.
Each item accepts the following properties:
The id of your PDF template
The object containing the variables from your PDF template
If you're using our embedded white-label solution, you can pass the UUID of
your customer to generate the PDF of the customized template
If true, will return a .PNG file instead of a .PDF file
The id of the active s3 connection you want to store your generated file on.
(only available in the high plan)
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)
This object containing the metadata for your PDF. [See all the options
here](/api-reference/options/pdf-metadata).
If true, will hide the footer and the header elements on the first page of the
generated PDF
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](/api-reference/options/debug-mode)
If true, the request will return immediately with a `batchRequestId` and
`statusUrl`. You can poll the [Get Batch PDF Status](/api-reference/pdf-status/get-batch)
endpoint to track progress.
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`.
A URL to receive a POST request when the batch is complete. The webhook payload
will contain the full batch status and results.
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`:
```json theme={null}
{
"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](/api-reference/pdf-status/get-batch) endpoint.
## Payload Size Limit
The request body is limited to **3MB**. Since batch requests contain multiple items, this limit can be reached when sending many items with large `data` objects.
If your request exceeds this limit, you'll receive a `413` status code with the following error:
```json theme={null}
{
"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](/api-reference/pdf-status/get-batch) endpoint with the `batchRequestId`.
To check the status of an individual PDF within the batch, use the [Get PDF Status](/api-reference/pdf-status/get) endpoint with the individual `requestId` from the results.