POST /batches
POST
Create Bulk Batch Job
Submits a large collection of receipt files or claims for parallel batch execution. The HeyPeppy work queue distributes tasks across isolated Cloud Tasks workers, enforces tenant rate limits, and sends aggregated progress notifications or per-task webhooks.
Headers
HTTP Headers| Parameter | Type | Description |
|---|---|---|
Authorizationrequired | string | Bearer token format: Bearer <API_KEY> Example: Bearer pep_live_99281a8b |
X-Tenant-IDoptional | string | B2B Tenant identifier. Example: stepup |
Content-Typerequired | string | application/json |
Query Parameters
URL Query String| Parameter | Type | Description |
|---|---|---|
concurrencyLimitoptional | integer default: 20 | Maximum concurrent tasks to process simultaneously (1-50, default: 20). Example: 25 |
Request Body
application/json| Field | Type | Description |
|---|---|---|
tenantIdoptional | string | Tenant organization identifier. Example: stepup |
batchTyperequired | string (enum) | Type of jobs in this batch (receipt_extraction or submission_audit). Example: receipt_extraction |
webhookUrloptional | string (URI) | Webhook invoked once all tasks in the batch have reached completion. Example: https://portal.partner.org/api/webhooks/batch-complete |
itemsrequired | array<object> | Array of up to 1,000 items matching ReceiptExtractionRequest or SubmissionAuditRequest. |
Responses
3 status codes202 AcceptedBulk batch accepted and individual tasks queued.
{
"batchId": "batch_987xyz109",
"totalItems": 2,
"status": "processing",
"createdAt": "2026-09-15T15:45:00Z",
"pollUrl": "https://api.heypeppy.ai/v1/batches/batch_987xyz109"
}Interactive Test Console
concurrencyLimit