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.
JWT-only. Rate limits apply per workspace (same as single renders).
:::info Async — poll for status
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 · application/json
{
"rows": [
{ "name": "Alice", "total": "$1,200" },
{ "name": "Bob", "total": "$950" }
],
"output": "zip",
"fileNamePattern": "invoice-{{name}}"
}
| 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}}). |
Returns { jobId }.
Submit a batch job (CSV / XLSX upload)
POST /api/templates/{id}/render-batch/upload · JWT · multipart/form-data
Upload a .csv or .xlsx file. Each data row becomes one render. Column
headers map to template {{tokens}}. Returns { jobId }.
Get job status
GET /api/templates/{id}/render-batch/jobs/{jobId} · JWT
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
Returns the workspace's recent batch jobs for this template.
Download result
GET /api/templates/{id}/render-batch/jobs/{jobId}/result · JWT
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.