Batch Generate PDFs

Batch submission requests let you create multiple PDFs in parallel with a single call to the DocSpring API. Each item in the batch can point to a different template, supply different data, and choose between test or live mode.

Endpoint

POST /api/v1/submissions/batches

API Reference: Batch Generate PDFs View all parameters, example requests/responses, and code samples

Request Structure

Provide an array of submissions. Every entry accepts the same payload as a standard submission request:

{
  "submissions": [
    {
      "template_id": "tpl_contract",
      "data": { "name": "John Smith" },
      "test": true,
      "metadata": { "pdf_filename": "contract_draft_john_smith" }
    },
    {
      "template_id": "tpl_invoice",
      "data": { "name": "Acme Corp" },
      "test": false,
      "wait": false
    }
  ]
}

Response Format

Batch responses include a batch object and an array of child submissions:

{
  "batch": {
    "id": "bat_123",
    "status": "processed",
    "created_at": "2024-02-01T12:00:00Z"
  },
  "submissions": [
    {
      "id": "sub_first",
      "status": "processed",
      "download_url": "https://.../sub_first.pdf"
    },
    {
      "id": "sub_second",
      "status": "pending"
    }
  ]
}

When you set wait=false on any submission, the batch response may return before the PDF is ready. Poll each submission with GET /api/v1/submissions/{id} or listen for the submission.completed webhook.

Limits & Best Practices

Up to 50 submissions per batch request.
Mix templates freely – each item can target a different template.
Test vs. live mode – set test per submission.
Back pressure – prefer batch requests when generating many documents to avoid hitting rate limits with individual calls.
Webhooks – enable webhooks if you need to know when asynchronous submissions finish processing.

Generate PDFs Overview Understand submission payloads, processing modes, and related workflows

Sync vs. Async Processing Choose the right processing strategy and learn when to poll or use webhooks

Special Newline Characters Replace literal newline characters with %%LF%% when integrations strip them

Customize Title & Filename Control PDF metadata so batch jobs produce well-named files