Batches

Create a batch

Renders one template version for many items — a JSON items array (≤ 25 MB body) or a CSV from POST /v1/uploads with an optional csv_mapping — sharing output, delivery and webhook. Items become ordinary renders (source: batch), released under your plan's bulk concurrency; combine adds a ZIP of all outputs and/or one merged PDF. Answers 202 right away; follow progress with GET /v1/batches/{id} or the batch.progress / batch.completed webhooks. Live items are billed as they are released: if the render limit is reached mid-batch, the batch pauses (paused, one batch.progress) and resumes on its own once renders are available again.

post/v1/batches

Request

  • Base URL: https://api-eu.dynamicdocumentapi.com
  • URL: https://api-eu.dynamicdocumentapi.com/v1/batches
  • Auth: one of:
    • HTTP bearer
    • API key in header X-API-Key

Headers

Idempotency-Keystring

Replays the stored response for 24 h; a different body with the same key → 422.

Request body

csv_mappingobject nullable
csv_upload_idstring nullable
enginestring nullable
metadataobject nullable
referencestring nullable
template_idstring required
testboolean nullable

Response

Batch accepted (Location: /v1/batches/{id}).

canceledinteger
completed_atstring date-time nullable
created_atstring date-time required
failedinteger
idstring required
metadataobject
object'batch' required
pendinginteger

Items without a final status yet.

progressnumber

Finished items ÷ total.

referencestring nullable
status'queued' | 'processing' | 'completed' | 'failed' | 'canceled' required
succeededinteger
template_idstring
template_versioninteger nullable

Version number rendered.

testboolean required
totalinteger required

Example response

{
  "error": {
    "code": "item_files_expired"
  },
  "files": [
    {
      "bytes": 1843200,
      "content_type": "application/zip",
      "file_id": "file_01J9ZM1X3F7R8K2C4V6B8N0P2R",
      "filename": "certificates.zip"
    }
  ],
  "id": "bat_01J9ZN4T6V8X0Z2B4D6F8H0K2M",
  "template_id": "tpl_01J9ZK3M7Q8V5W2X4Y6Z8A0B1C"
}

Changes

No recorded changes to this operation across all 2 revisions of this API.