Batch generation

Batch generation produces one PDF per row of a dataset and bundles the results into a ZIP. It is an asynchronous job: you submit rows, poll for status, then download.

Batch is plan-gated by the batchGenerate feature. Without it, these endpoints return HTTP 403 INSUFFICIENT_PERMISSIONS. Each row costs 1 credit; the whole batch is checked for credit coverage before it is queued. See Credits & plans.

All paths are relative to https://api.imaginepdf.com/api/v1.

Submit a batch


POST /designs/:designId/batch

Path parameters

Param	Type	Required	Notes
`designId`	string	yes	The design id to render for every row.

Body

Field	Type	Required	Notes
`rows`	array	yes	Each element is a `data` object (variable → value). 1–100 rows.


curl -X POST "https://api.imaginepdf.com/api/v1/designs/design_abc123/batch" \
  -H "X-API-Key: $IMAGINEPDF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rows": [
      { "invoice_number": "INV-001", "customer_name": "Acme Corp",  "amount": "$100" },
      { "invoice_number": "INV-002", "customer_name": "Globex Inc", "amount": "$250" }
    ]
  }'

Response 202 Accepted


{
  "status": "success",
  "data": {
    "jobId": "job_abc123xyz",
    "status": "queued",
    "total": 2,
    "designId": "design_abc123"
  },
  "error": null
}

Up to 100 rows per batch.

Poll job status


GET /batches/:jobId


curl https://api.imaginepdf.com/api/v1/batches/job_abc123xyz \
  -H "X-API-Key: $IMAGINEPDF_API_KEY"

Response 200 OK


{
  "status": "success",
  "data": {
    "jobId": "job_abc123xyz",
    "status": "processing",
    "total": 2,
    "completed": 1,
    "failed": 0,
    "createdAt": "2026-06-08T12:00:00Z",
    "updatedAt": "2026-06-08T12:01:00Z"
  },
  "error": null
}

status is one of: queued, processing, completed, failed. Poll until it reaches completed.

Download the result


GET /batches/:jobId/download

Returns a presigned URL to the output ZIP (one PDF per successful row).


curl https://api.imaginepdf.com/api/v1/batches/job_abc123xyz/download \
  -H "X-API-Key: $IMAGINEPDF_API_KEY"

Response 200 OK


{
  "status": "success",
  "data": {
    "downloadUrl": "https://storage.imaginepdf.com/batch_output.zip?signature=...",
    "expiresIn": 3600
  },
  "error": null
}


curl -L -o batch.zip "<downloadUrl>"

A typical loop

POST /designs/:id/batch → get jobId.
GET /batches/:jobId every few seconds until status is completed.
GET /batches/:jobId/download → fetch the ZIP within expiresIn seconds.

For a complete CSV parser, row mapping, polling deadline, and restart-safe Node.js workflow, see Bulk PDF generation from CSV .