VaultDispatch

VaultDispatch is a governed batch document generation engine. Submit a payload with hundreds of records, get a validation report, obtain approval, and let the Processor render and deliver each document independently — with a per-record audit trail and VaultDelivery integration.

VaultDispatch extends the VaultPDF render engine with a governed batch layer. Rather than submitting one document at a time, you submit an array of records in a single POST /api/render call. VaultDispatch validates the records, generates a batch intake receipt, routes to an approver (when configured), and — after approval — hands off to the Processor to render and deliver each document independently.

Enterprise Feature

VaultDispatch requires the vaultDispatch feature gate on your licence. Set features.vaultDispatch: true in the render request.

Auto-derive: If your template already has distribution.enabled: true and distribution.requireApproval: true in templateSettings, the vaultDispatch feature is activated automatically — you do not need to pass it explicitly. Passing it explicitly is recommended for clarity.

What VaultDispatch Does

Batch Record Validation

Each record in the batch is validated against the template's field rules and filename template before any PDF is rendered. An intake receipt PDF summarises the readiness of each record.

Governed Approval Flow

When requireApproval is true, the batch enters pending-approval state. A designated approver reviews the intake receipt and decides to approve, request changes, or reject before any PDFs are generated.

Independent Per-Record Processing

After approval, the Processor renders each record independently. Each gets its own correlationId, PDF, and audit trail. Failures in one record do not block others.

VaultDelivery Integration

Each rendered PDF can be delivered to its recipient via VaultDelivery secure email automatically. The recipientEmail field in each record drives delivery.

Distribution Modes

Individual mode renders one PDF per record. Combined mode merges all records into a single PDF. Both modes support ZIP bundle download.

Partial Failure Handling

A batch that processes some records successfully and others with errors completes in partially-failed state. Processed and error counts are tracked separately.

Batch Lifecycle States

State	Description
`pending-approval`	Batch submitted and validated; awaiting approver decision.
`invalid`	One or more records failed validation with `error` severity. Batch cannot proceed until corrected and resubmitted.
`changes-requested`	Approver returned the batch with comments. Submitter must correct and resubmit.
`approved`	Approver accepted the batch. About to be enqueued for processing.
`queued`	Enqueued to the `vaultpdf-low` Service Bus queue. Awaiting Processor pickup.
`processing`	Processor is actively rendering records. `processedCount` and `errorCount` update as records complete.
`completed`	All records processed successfully.
`partially-failed`	Processing finished; some records succeeded and some failed.
`rejected`	Approver rejected the batch. No PDFs are produced.
`cancelled`	Cancelled by the submitter before processing began.

Template Distribution Settings

Batch dispatch is controlled by a distribution block in the template's templateSettings. This block can be set in the .vpdf template file or overridden per request in templateSettings.distribution.

{
  "templateSettings": {
    "distribution": {
      "mode": "individual",
      "requireApproval": true,
      "fileNameTemplate": "Statement_{{accountNumber}}_{BATCHID_1}",
      "approversEmail": "[email protected]",
      "deliveryConfig": {
        "mode": "secure-email",
        "expiresInHours": 168
      },
      "zipBundle": false
    }
  }
}

Setting	Type	Description
`mode`	`individual` \| `combined`	`individual` renders one PDF per record. `combined` merges all records into one PDF. Default: `individual`.
`requireApproval`	`boolean`	When `true`, batch enters `pending-approval` before processing. When `false`, the batch is auto-approved and queued immediately.
`fileNameTemplate`	`string`	Filename pattern for each rendered PDF. Supports `{{fieldName}}` tokens from the record, `{BATCHID_1}` (1-based index), `{BATCHID}` (0-based).
`approversEmail`	`string \| string[]`	Approver email(s) to notify when the batch reaches `pending-approval`. Overridden by the tenant-level approver config if absent.
`deliveryConfig.mode`	`secure-email` \| `none`	Whether to create a VaultDelivery session per record after rendering. `none` disables delivery; `secure-email` creates a session for each `recipientEmail` in the record.
`deliveryConfig.expiresInHours`	`number`	Delivery session TTL. Defaults to 168 hours (7 days).
`zipBundle`	`boolean`	When `true` (individual mode only), all rendered PDFs are also bundled into a single ZIP and stored in blob storage.

How Batch Intake Works

Batch dispatch is triggered via the standard render endpoint with an array dataSource and the vaultDispatch feature enabled.

Submit the batch via POST /api/render

Pass dataSource as an array of records. Include distribution settings in templateSettings and set features.vaultDispatch: true.

Dispatcher validates records

Each record is checked against the template's validation rules and the fileNameTemplate. A DISPATCH_READY or INVALID status is assigned per record.

Batch intake receipt returned

The Dispatcher returns HTTP 202 with a batch intake receipt PDF as the response body. The X-VaultPDF-BatchId and X-VaultPDF-CorrelationId headers carry the batch identifiers. File the receipt against the originating record in your source system.

Approval (when requireApproval: true)

The batch enters pending-approval. The configured approver(s) receive an email notification. The approver reviews the intake receipt via VaultLifecycle and calls POST /api/dispatch/batch/{batchId}/decide.

Processing

After approval (or immediately when requireApproval: false), the batch is enqueued. The Processor renders each record independently, uploads each PDF, posts a VaultPDF_Activity item per record, and (if delivery is configured) creates a VaultDelivery session per recipient.

Per-Record Data Requirements

Each record in the dataSource array is a plain JSON object. The fields available depend on the template, but two fields have special meaning for VaultDispatch:

Field	Description
`recipientEmail`	Email address for VaultDelivery session creation. Required when `deliveryConfig.mode: secure-email`. Supports semicolon-separated addresses for multiple recipients per record.
`recipientName`	Display name used in the delivery notification email. Optional. Supports semicolon-separated names aligned by index to `recipientEmail`.

The documentIdTemplate option in options allows dynamic document IDs per record using {{fieldName}} tokens:

{
  "options": {
    "documentIdTemplate": "STMT-{{accountNumber}}"
  }
}

API Reference

Full reference for batch management endpoints: list, get, decide, and cancel.

VaultDispatch API Reference Batch Dispatch Tutorial

VaultDispatch

API Reference

On this page