Batch Render — Mail Merge
Tag: Batch · Version: v1 · Stability: 🟡 Beta
Generate many PDFs from a single template in one call — one render per data row. The result is either a ZIP of per-row files or a single merged PDF, produced by a background job with live progress and partial-failure reporting.
Authenticate with a JWT or an X-Api-Key. Rate limits apply per workspace
(same as single renders).
Batch jobs run in the background. Submit the job, get back a jobId, poll the
status endpoint until completed or failed, then download the result.
Submit a batch job (JSON rows)
POST /api/templates/{id}/render-batch · JWT or API key · application/json
{
"rows": [
{ "name": "Alice", "total": "$1,200" },
{ "name": "Bob", "total": "$950" }
],
"output": "zip",
"fileNamePattern": "invoice-{{name}}",
"theme": { "primary": "#E11D48" }
}
| Field | Type | Required | Notes |
|---|---|---|---|
rows | array of objects | ✅ | One render per element. Max 2,000 rows. |
output | "zip" | "merged" | ✅ | zip → per-row PDFs in a ZIP; merged → one concatenated PDF. |
fileNamePattern | string | null | ✅ | Token pattern for filenames inside the ZIP (e.g. invoice-{{name}}). |
theme | object | null | — | Brand colours applied to every row of the batch: { "primary", "accent" }, each #rgb / #rrggbb or null. One theme per batch. |
theme follows the same rules as on a single render — see
Rendering → Brand colours. It is validated
when the job is submitted (an unknown key or a bad colour is a 400) and applied to
each row. To render different rows in different colours, submit one batch per theme.
Returns { jobId }.
Submit a batch job (CSV / XLSX upload)
POST /api/templates/{id}/render-batch/upload · JWT or API key · multipart/form-data
Upload a .csv or .xlsx file. Each data row becomes one render. Column
headers map to template {{tokens}}. Returns { jobId }.
The upload form takes no theme: spreadsheet batches render in the template's
own colours. Use the JSON endpoint above to theme a batch.
Get job status
GET /api/templates/{id}/render-batch/jobs/{jobId} · JWT or API key
Poll this endpoint until status is completed or failed.
{
"jobId": "uuid",
"status": "processing",
"total": 50,
"completed": 23,
"failed": 0
}
status | Meaning |
|---|---|
pending | Queued, not yet started. |
processing | Running — completed + failed show progress. |
completed | All rows attempted; download the result. |
failed | Job-level failure (not a partial row failure). |
List recent jobs
GET /api/templates/{id}/render-batch/jobs · JWT or API key
Returns the workspace's recent batch jobs for this template.
Download result
GET /api/templates/{id}/render-batch/jobs/{jobId}/result · JWT or API key
Returns the ZIP or merged PDF. Only available when status === "completed".
Results expire after 24 hours.
Partial failures
If individual rows fail to render, they are skipped and reported in the status
response — the job still completes. A job-level failure (e.g. the template is
missing) marks the whole job failed.
Row cap
Maximum 2,000 rows per job. Larger datasets should be split across multiple jobs.