VaultDispatch API Reference
HTTP endpoint reference for batch dispatch management — list batches, get batch detail, approve or reject, and cancel.
Batch dispatch is initiated via POST /api/render — there is no separate batch creation endpoint. Once a batch exists, the endpoints below manage its lifecycle.
All endpoints require a valid Entra ID JWT and the vaultDispatch feature on your licence.
Base URL
All paths are relative to your Dispatcher Function base URL, e.g. https://<your-dispatcher>.azurewebsites.net.
Submit a Batch
POST /api/renderBatch dispatch uses the standard render endpoint with dataSource as an array and features.vaultDispatch: true.
Auth: Entra ID JWT
Request body:
{
"templatePath": "templates/account-statement.vpdf",
"options": {
"correlationId": "batch-stmt-may-2026",
"documentId": "BATCH-STMT-MAY-2026",
"generatedBy": "[email protected]",
"sourceSystem": "D365_FO",
"documentIdTemplate": "STMT-{{accountNumber}}"
},
"dataSource": [
{
"accountNumber": "ACC-001",
"accountName": "Contoso Ltd",
"recipientEmail": "[email protected]",
"statementPeriod": "May 2026",
"balance": 850.00
},
{
"accountNumber": "ACC-002",
"accountName": "Fabrikam Inc",
"recipientEmail": "[email protected]",
"statementPeriod": "May 2026",
"balance": 2100.00
}
],
"templateSettings": {
"distribution": {
"mode": "individual",
"requireApproval": true,
"fileNameTemplate": "Statement_{{accountNumber}}_{BATCHID_1}",
"approversEmail": "[email protected]",
"deliveryConfig": {
"mode": "secure-email",
"expiresInHours": 168
}
}
},
"features": {
"vaultDispatch": true
}
}Response 202:
Response body is the batch intake receipt PDF (binary). The batch identifiers are in the response headers:
| Header | Description |
|---|---|
X-VaultPDF-BatchId | Unique batch identifier. Use this with all /api/dispatch/batch/* endpoints. |
X-VaultPDF-CorrelationId | Correlation ID for the batch activity record. Links to the VaultPDF_Activity item in SharePoint. |
X-VaultPDF-DispatchReadiness | READY, PARTIAL, or INVALID — overall validation outcome across all records. |
INVALID batches return 422
When X-VaultPDF-DispatchReadiness is INVALID, the status code is 422 Unprocessable Entity. The intake receipt PDF still describes which records failed validation and why. Correct the records and resubmit.
List Batches
GET /api/dispatch/batchReturns all batches for the authenticated tenant, optionally filtered by state.
Auth: Entra ID JWT
Query params:
| Param | Description |
|---|---|
state | Optional. Filter by BatchDispatchState. E.g. ?state=pending-approval. |
Response 200:
{
"total": 2,
"batches": [
{
"batchId": "a3f1c2d4-8e9b-4f0a-b2c3-1d4e5f6a7b8c",
"state": "pending-approval",
"dispatchReadiness": "READY",
"title": "May 2026 Account Statements",
"documentCount": 150,
"readyCount": 148,
"failedCount": 0,
"warningCount": 2,
"activityItemId": "42",
"createdAt": "2026-06-09T10:00:00.000Z",
"updatedAt": "2026-06-09T10:00:05.000Z"
}
]
}Get Batch
GET /api/dispatch/batch/{batchId}Returns the full detail of a single batch, including validation results, processing counters, and decision history.
Auth: Entra ID JWT
Response 200:
{
"batchId": "a3f1c2d4-8e9b-4f0a-b2c3-1d4e5f6a7b8c",
"state": "completed",
"dispatchReadiness": "READY",
"title": "May 2026 Account Statements",
"templatePath": "templates/account-statement.vpdf",
"documentCount": 150,
"readyCount": 148,
"failedCount": 0,
"warningCount": 2,
"processedCount": 150,
"submittedBy": "[email protected]",
"approvedBy": "[email protected]",
"createdAt": "2026-06-09T10:00:00.000Z",
"decidedAt": "2026-06-09T10:15:00.000Z",
"queuedAt": "2026-06-09T10:15:01.000Z",
"completedAt": "2026-06-09T10:42:00.000Z",
"decisionComments": "Validated — proceed",
"validationResults": [
{ "index": 0, "status": "valid" },
{ "index": 1, "status": "warning", "messages": ["Balance field is zero"] }
]
}Decide (Approve / Reject / Request Changes)
POST /api/dispatch/batch/{batchId}/decideRecords the approver's decision. Only batches in pending-approval or changes-requested state can be decided.
Auth: Entra ID JWT (approver)
Request body:
{
"decision": "approve",
"comments": "Validated against AP system — proceed."
}| Field | Type | Required | Description |
|---|---|---|---|
decision | approve | reject | request-changes | Yes | The approver's decision. approve enqueues the batch for processing. reject ends the batch with no PDFs produced. request-changes returns the batch to changes-requested state with the comments. |
comments | string | No | Free-text comments visible in the batch record and activity timeline. |
Response 200:
{
"batchId": "a3f1c2d4-8e9b-4f0a-b2c3-1d4e5f6a7b8c",
"state": "queued",
"decidedAt": "2026-06-09T10:15:00.000Z"
}Auto-approve
When distribution.requireApproval: false in the template settings, the batch is auto-approved at intake time and enters queued state immediately — no /decide call is required.
Cancel Batch
POST /api/dispatch/batch/{batchId}/cancelCancels a batch that has not yet started processing. Cancellable states: pending-approval, changes-requested.
Auth: Entra ID JWT
Response 200:
{ "batchId": "a3f1c2d4-...", "state": "cancelled" }Tracking Individual Records
Each record in the batch gets its own correlationId (generated by the Processor). To track individual records after processing:
- Query the
VaultPDF_ActivitySharePoint list filtered byReferenceID={batchId}— all child activity items link back to the batch viaReferenceID. - Use VaultLifecycle Lifecycle Search with
?batchId={batchId}to view all documents from the batch. - Query delivery sessions:
GET /api/delivery-sessions?correlationId={itemCorrelationId}.
VaultDispatch Overview
Batch lifecycle states, distribution template settings, per-record data requirements, and the full approval flow.
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.
VaultLifecycle
VaultLifecycle is a SharePoint-hosted workspace that provides a unified operational view of every document generated by Vault Platform, with search, filters, timeline, signing, delivery, workflow, and configuration in a single interface.