Async batch rendering

Use the Integration Batch endpoints when you need to render many documents in one job without uploading CSV or Excel in the admin UI.

Output kind (HTML vs PDF) is always selected by the URL path—the same pattern as synchronous POST /api/v1/render/html and POST /api/v1/render/pdf. List, download, and ZIP endpoints are also split by format; do not mix HTML and PDF output IDs in one request.

Flow

1. POST /api/v1/render/batches/html or POST /api/v1/render/batches/pdf with templateId, deliveryChannel (none for render-only), and items[].variables.
2. Receive 202 with processBatchId and batchId. Always persist processBatchId from the response when you did not supply one.
3. Optionally set callbackUrl (HTTPS) on batch submit; see Completion callback below.
4. GET /api/v1/render/processes/{processBatchId}/outputs/html or .../outputs/pdf (paginated) to list output ids for that format—poll until outputs appear even when using a callback.
5. GET /api/v1/render/outputs/html/{outputId} or .../pdf/{outputId}, or POST .../outputs/html/download / .../pdf/download for a ZIP.

Reuse the same processBatchId on later batch submissions to group multiple template batches into one process (HTML and PDF batches can share a process; list and download per format).

Completion callback

callbackUrl is optional on POST /api/v1/render/batches/html or .../pdf. Use an HTTPS URL; invalid URLs return 400 (see Error handling).

When the process reaches a terminal state (completed or completed_with_errors), the platform enqueues an outbound POST to your URL outside the render worker. Treat the callback as a notification, not the only completion signal:

• Continue to poll step 4 until outputs exist.
• Your handler should respond with 2xx quickly; delivery may be at-least-once—dedupe on processBatchId and type.

Automatic retries

Platform defaults (configurable by the operator):

1. Aggressive phase — exponential backoff (about 30s base, capped interval) for up to 24 hours after the first delivery attempt.
2. Daily phase — up to seven attempts about 24 hours apart.
3. attention_required — no further automatic POSTs until an org admin acts.

If delivery stalls

Org admins with permission integration.callbacks.manage can open Settings → Integration render callbacks in the admin UI to Retry (one immediate attempt, then resume daily automatic retries) or Abandon (no further POSTs for that process). Rendered files remain available via the Integration API list/download endpoints. Integrators cannot retry or abandon callbacks with an API key.

Inbound POST body

Content-Type: application/json. There is no X-CommsPliant-Signature header (unlike organization webhook subscriptions).

{
  "type": "integration_render_process.completed",
  "processBatchId": "68463aea-7762-474b-a53c-d14742900b65",
  "status": "completed",
  "completionReason": "expected_reached",
  "expectedDocumentCount": 1500,
  "batches": { "total": 1, "completed": 1, "failed": 0 },
  "documents": { "total": 100, "rendered": 98, "failed": 2 }
}

status is completed or completed_with_errors. Fields completionReason (expected_reached | idle_timeout) and optional expectedDocumentCount describe how the process closed—see Completion modes. The OpenAPI schema is IntegrationRenderProcessCompletedCallback.

Process id (processBatchId)

A process can include one or more batch jobs. Each submit returns:

• processBatchId — the process you are building (use this in list/download URLs and on follow-up submits).
• batchId — one async render job for this submit only.

You can start a process in either way:

• Omit processBatchId — the platform assigns a new UUID and returns it in the 202 body.
• Set processBatchId to a stable client-chosen UUID — the platform creates the process on the first submit when that id does not exist yet for your organization, or appends another batch when the process is still open.

If the process is already completed or closed, resubmitting with the same processBatchId returns 409 (integration render process is not open). Processes close after completion rules are met (planned row total or open-ended idle grace), not merely when the last in-flight job finishes.

Optional expectedDocumentCount declares a planned statement size; see Completion modes.

Limits

Platform defaults (configurable in super admin):

• 500 items per batch
• 10 parallel open processes per organization
• 100 max page size when listing outputs
• 50 outputs per ZIP download request
• 900 seconds (15 minutes) default idle grace before open-ended processes complete (integration_batch_completion_grace_seconds in super admin)

Admin visibility

Each batch creates a normal render job visible under Render jobs in the admin UI (marked API when submitted via integration).

Stalled completion callbacks appear under Settings → Integration render callbacks for admins with integration.callbacks.manage.

Delivery

deliveryChannel is required on submit: none, email, sms, or postal. Only none (render-only) is accepted today; other values return 400. Per-item delivery hints in OpenAPI are reserved for a future release.