Batch Document Generation

Generate multiple documents from a single template in one API call. Batch generation is ideal for invoices, reports, certificates, and other high-volume document workflows.

Creating a Batch Job

cURL

curl -X POST "https://api.propper.ai/v1/docgen/batches" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "tmpl_abc123",
    "outputFormat": "PDF",
    "items": [
      {
        "mergeData": {
          "customerName": "Acme Corp",
          "amount": "$1,500.00"
        }
      },
      {
        "mergeData": {
          "customerName": "Globex Inc",
          "amount": "$2,300.00"
        }
      },
      {
        "mergeData": {
          "customerName": "Initech LLC",
          "amount": "$800.00"
        }
      }
    ],
    "settings": {
      "concurrency": 5,
      "continueOnError": true
    }
  }'

JavaScript

const response = await fetch('https://api.propper.ai/v1/docgen/batches', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    templateId: 'tmpl_abc123',
    outputFormat: 'PDF',
    items: [
      { mergeData: { customerName: 'Acme Corp', amount: '$1,500.00' } },
      { mergeData: { customerName: 'Globex Inc', amount: '$2,300.00' } },
      { mergeData: { customerName: 'Initech LLC', amount: '$800.00' } },
    ],
    settings: {
      concurrency: 5,
      continueOnError: true,
    },
  }),
});

const batch = await response.json();
console.log('Batch ID:', batch.id);

Response:

{
  "id": "batch_001",
  "templateId": "tmpl_abc123",
  "status": "PENDING",
  "totalItems": 3,
  "completedItems": 0,
  "failedItems": 0,
  "createdAt": "2024-01-15T10:00:00Z"
}

Batch Settings

Setting	Type	Default	Description
concurrency	number	5	Max documents generated simultaneously (1-20)
continueOnError	boolean	false	Continue processing if individual items fail

Monitoring Progress

Poll the batch status to track progress.

curl "https://api.propper.ai/v1/docgen/batches/{batchId}" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response (in progress):

{
  "id": "batch_001",
  "status": "PROCESSING",
  "totalItems": 3,
  "completedItems": 2,
  "failedItems": 0,
  "progress": 66.7
}

Batch Status Flow

Listing Batch Items

View individual results within a batch.

curl "https://api.propper.ai/v1/docgen/batches/{batchId}/items?page=1&pageSize=20" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:

{
  "data": [
    {
      "id": "item_001",
      "documentId": "doc_aaa",
      "status": "GENERATED",
      "mergeData": { "customerName": "Acme Corp" }
    },
    {
      "id": "item_002",
      "documentId": "doc_bbb",
      "status": "GENERATED",
      "mergeData": { "customerName": "Globex Inc" }
    },
    {
      "id": "item_003",
      "documentId": null,
      "status": "FAILED",
      "error": { "code": "MERGE_DATA_MISSING", "message": "Field 'amount' required" }
    }
  ]
}

Downloading Batch Results

Download all successfully generated documents as a ZIP archive.

curl "https://api.propper.ai/v1/docgen/batches/{batchId}/download" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -o batch-results.zip

Cancelling a Batch

Cancel a batch that is PENDING or PROCESSING. Requires docgen:admin scope.

curl -X POST "https://api.propper.ai/v1/docgen/batches/{batchId}/cancel" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Retrying Failed Items

Retry failed items in a completed batch. Requires docgen:admin scope.

curl -X POST "https://api.propper.ai/v1/docgen/batches/{batchId}/retry" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

This creates a new batch containing only the previously failed items.