Calculate payroll for multiple employees
Payroll
Calculate payroll for multiple employees
Calculate payroll for 1–500 employees in a single request.
**Synchronous mode** (≤50 employees or `options.async=false`):
Returns all results immediately. P99 target: <2s for 50 employees.
**Asynchronous mode** (`options.async=true` with >50 employees):
Returns a job ID immediately (HTTP 202). Poll `GET /v1/payroll/jobs/{id}`
for results. Asynchronous batch is not fully implemented in v1 — the
endpoint returns a placeholder response indicating this.
**Error handling**: by default (`options.fail_fast=false`), employee-level
errors do not abort the batch. Failed employees appear in the response with
`status: "error"` and an error detail. Set `fail_fast=true` to abort on
the first error.
POST
Calculate payroll for multiple employees
Authorizations
API key authentication. Send your API key as: Authorization: Bearer <your_api_key>
Body
application/json
Request body for POST /v1/payroll/batch.
Processes up to 500 employees in one request. Employees ≤ 50 are processed synchronously. Above 50 employees, set options.async=true to receive a job ID for polling.
Pattern:
^[A-Z]{2}$Example:
"MX"
Example:
"ordinario"
Required range:
2020 <= x <= 2030Example:
2024
Payroll period definition.
Employer-side inputs for a payroll calculation.
List of employees to calculate. 1–500 employees per request.
Required array length:
1 - 500 elementsOptions specific to batch requests.
Response
Batch completed synchronously.
- BatchResponse
- AsyncBatchResponse
Synchronous batch calculation response (≤50 employees).
Batch job ID (ULID).
Allowed value:
"completed"