When to use one

Anything that happens to a group rather than a person: certificates for a cohort, monthly statements, renewal notices. Sending those one request at a time works, but a batch gives you a single job to watch and one callback at the end instead of hundreds.

Submitting

POST a template id and a list of data objects — one per document — to/api/v1/generate/batch. The response is immediate and carries a job id; the rendering happens behind it.

POST /api/v1/generate/batch

{
  "template_id": "tpl_invoice_a4",
  "items": [
    { "contact": { "full_name": "Dana Reyes" }, "total": 1840.00 },
    { "contact": { "full_name": "Sam Okafor" }, "total": 920.50 }
  ],
  "callback_url": "https://example.com/hooks/batch-done"
}

Limits

A single job takes at most 500 items. Larger runs are split across jobs. There is no cap on how many documents you may generate in a period — see pricing — the limit here is per request, not per month.

Watching a job

GET /api/v1/jobs/:id reports where a run has got to. If you supplied a callback_url, it is called once the job finishes, so polling is optional.

Failures

An item that fails to render is recorded against the job with its error and does not stop the rest of the run. Failed renders are logged and never billed.

Requirements

Batch runs need the queue to be reachable. If it is not, the endpoint says so with a 503 rather than accepting work it cannot do.