Batch generation walkthrough.

The API reference documents each endpoint on its own. This page runs them in order.

• A DOCX template uploaded to BulkRender, and its templateId.
• An API key, sent as X-API-Key.
• Enough credits. DOCX costs 1 credit per document, PDF costs 2.

One row per document. One column per template variable. Column headers must match the variable names in your template exactly, including case.

Four rules save most of the debugging time:

1. Pre-compute every total. BulkRender fills values, it never calculates them. Subtotals, tax, and grand totals must already sit in a column.
2. Pre-format currency and dates as text. Write £1,240.00 and 14 Mar 2026, not a raw number or a date serial. The engine inserts what you send, as text.
3. Clean spreadsheet error values first. Cells holding #N/A, #REF!, #VALUE! and similar cause the row to be skipped. See step 6.
4. Repeating tables need nested data. A line-items table in your template maps to an array inside the record, so build it in JSON. CSV upload in the batch UI is flat and cannot carry arrays.

Check the row count against your plan limit before you send.

The ZIP itself is capped at 50 MB, and each document at 10 MB. Split very large runs into several batches.

Each spreadsheet row becomes one object in the records array. A record with a repeating table looks like this:

{
  "invoice_no": "INV-1001",
  "customer": "Alice Ltd",
  "due_date": "14 Mar 2026",
  "amount_due": "£1,240.00",
  "items": [
    { "desc": "Design retainer", "qty": "1", "line_total": "£1,000.00" },
    { "desc": "Hosting", "qty": "4", "line_total": "£240.00" }
  ]
}

In the template, items is a loop: wrap the repeating table row in {{#items}} and {{/items}}, then use the item's own fields inside it.

curl -X POST https://api.bulkrender.com/api/documents/generate-batch \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Idempotency-Key: invoices-2026-03-14-run1" \
  -d '{
    "templateId": "c5f2e8a1-...",
    "records": [ ... ],
    "outputFormat": "pdf"
  }'

What comes back depends on size.

A 202 body:

{
  "jobId": "9f31c0b2-...",
  "status": "processing",
  "progress": { "completed": 0, "total": 50, "failed": 0 }
}

curl https://api.bulkrender.com/api/documents/batch-jobs/9f31c0b2-... \
  -H "X-API-Key: YOUR_API_KEY"

{
  "status": "success",
  "data": {
    "jobId": "9f31c0b2-...",
    "status": "processing",
    "progress": { "completed": 32, "total": 50, "failed": 0 },
    "createdAt": "2026-03-14T09:12:04.881Z",
    "completedAt": null
  }
}

data.status moves through pending, processing, then completed or failed.

• completed: the response gains a url, the signed ZIP link.
• failed: read error_message on the response and fix the cause before resubmitting.

Poll every 3 to 5 seconds. Batches run with a 5 minute timeout and up to 5 documents in flight at once, so a 500 record PDF job takes minutes, not seconds. Do not poll in a tight loop.

The endpoint also accepts a synchronous batchId, so one polling routine handles both sizes. For a sync batch it returns "status": "completed" with "completedSynchronously": true.

The url is a signed link, valid for 1 hour by default and 24 hours at most.

curl -L -o invoices.zip "https://download.bulkrender.com/...batch-9f31c0b2.zip?X-Amz-Expires=3600&..."

If the link expires, poll the job again for a fresh one. Generated documents auto-expire after 3 days by default, so archive the ZIP on your side.

BulkRender validates rows before generating. A row holding a spreadsheet error value is skipped, never generated, and never charged.

When any row is skipped, the initial 201 or 202 response includes two extra fields:

{
  "jobId": "9f31c0b2-...",
  "status": "processing",
  "originalCount": 50,
  "progress": { "completed": 0, "total": 48, "failed": 0 },
  "skippedRecords": [
    { "index": 2, "reason": "Cell contains spreadsheet error value #N/A" },
    { "index": 17, "reason": "Cell contains spreadsheet error value #REF!" }
  ]
}

Three things to know:

1. index is the position in the array you sent, counted from 0. Map it back to your spreadsheet row before you report the error to a user.
2. These fields appear on the first response only. Later job polls do not repeat them, so log the first response.
3. If every record fails validation, the request returns 422 with the same skippedRecords list. Nothing generates and nothing is charged.