Skip to main content
POST
/
v1
/
payroll
/
batch
Calculate payroll for multiple employees
curl --request POST \
  --url https://api.example.com/v1/payroll/batch \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "country": "<string>",
  "scheme": "<string>",
  "year": 2025,
  "period": {
    "type": "monthly",
    "start_date": "2023-12-25",
    "end_date": "2023-12-25",
    "days": 16
  },
  "employer": {
    "id": "<string>",
    "rfc": "ABC123456XY0"
  },
  "employees": [
    {
      "id": "<string>",
      "daily_salary": 800,
      "monthly_salary": 1,
      "factor_integracion": 1.0493,
      "risk_class_rate": 0.00543,
      "overtime_amount": "0",
      "sunday_bonus_days": 0,
      "grocery_voucher_amount": "0",
      "infonavit_credit_amount": "0",
      "overrides": {},
      "period_override": {
        "type": "monthly",
        "start_date": "2023-12-25",
        "end_date": "2023-12-25",
        "days": 16
      }
    }
  ],
  "options": {
    "include_audit_trail": true,
    "include_diagram": false,
    "precision": 2,
    "async": false,
    "fail_fast": false
  }
}
'
{
  "id": "<string>",
  "country": "<string>",
  "scheme": "<string>",
  "year": 123,
  "total_requested": 123,
  "total_succeeded": 123,
  "total_failed": 123,
  "results": [
    {
      "employee_id": "<string>",
      "status": "success",
      "calculation": {
        "id": "<string>",
        "country": "<string>",
        "scheme": "<string>",
        "year": 123,
        "period": {
          "type": "monthly",
          "start_date": "2023-12-25",
          "end_date": "2023-12-25",
          "days": 16
        },
        "employee_id": "<string>",
        "summary": {
          "gross_salary": "<string>",
          "total_perceptions": "<string>",
          "total_deductions": "<string>",
          "net_salary": "<string>",
          "employer_contributions_total": "<string>",
          "employer_total_cost": "<string>"
        },
        "perceptions": [
          {
            "id": "<string>",
            "label": "<string>",
            "amount": "<string>",
            "taxable": true,
            "imss_base": true,
            "tags": [
              "<string>"
            ]
          }
        ],
        "deductions": [
          {
            "id": "<string>",
            "label": "<string>",
            "amount": "<string>",
            "tags": [
              "<string>"
            ],
            "bracket_applied": {}
          }
        ],
        "taxable_bases": [
          {
            "id": "<string>",
            "label": "<string>",
            "amount": "<string>",
            "formula": "<string>"
          }
        ],
        "employer_contributions": [
          {
            "table_id": "<string>",
            "label": "<string>",
            "total": "<string>",
            "components": [
              {
                "id": "<string>",
                "label": "<string>",
                "base": "<string>",
                "rate": "<string>",
                "amount": "<string>"
              }
            ]
          }
        ],
        "dsl_version": "<string>",
        "computed_at": "2023-11-07T05:31:56Z",
        "status": "success",
        "audit_trail": [
          {}
        ]
      },
      "error": {}
    }
  ],
  "computed_at": "2023-11-07T05:31:56Z",
  "status": "completed"
}

Authorizations

Authorization
string
header
required

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.

country
string
required
Pattern: ^[A-Z]{2}$
Example:

"MX"

scheme
string
required
Example:

"ordinario"

year
integer
required
Required range: 2020 <= x <= 2030
Example:

2024

period
Period · object
required

Payroll period definition.

employer
EmployerInput · object
required

Employer-side inputs for a payroll calculation.

employees
BatchEmployeeInput · object[]
required

List of employees to calculate. 1–500 employees per request.

Required array length: 1 - 500 elements
options
BatchOptions · object

Options specific to batch requests.

Response

Batch completed synchronously.

Synchronous batch calculation response (≤50 employees).

id
string
required

Batch job ID (ULID).

country
string
required
scheme
string
required
year
integer
required
total_requested
integer
required
total_succeeded
integer
required
total_failed
integer
required
results
BatchEmployeeResult · object[]
required
computed_at
string<date-time>
required
status
string
default:completed
Allowed value: "completed"