Skip to main content
POST
/
v1
/
payroll
/
simulate
Simulate multiple salary scenarios (not persisted)
curl --request POST \
  --url https://api.example.com/v1/payroll/simulate \
  --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
  },
  "employee": {
    "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": {}
  },
  "employer": {
    "id": "<string>",
    "rfc": "ABC123456XY0"
  },
  "simulation": {
    "scenarios": [
      {
        "label": "<string>",
        "daily_salary": 800,
        "overrides": {}
      }
    ]
  },
  "options": {
    "include_audit_trail": true,
    "include_diagram": false,
    "precision": 2
  }
}
'
{
  "id": "<string>",
  "country": "<string>",
  "scheme": "<string>",
  "year": 123,
  "results": [
    {
      "label": "<string>",
      "daily_salary": "<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": {}
        }
      ],
      "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",
  "is_simulation": true
}

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/simulate.

Identical computation to /calculate but:

  1. Results are NEVER persisted
  2. Supports multiple scenarios in a single request
  3. Intended for quote/preview UIs — "what would my cost be at X salary?"

The simulation flag is enforced at the route handler level, not here.

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.

employee
EmployeeInput · object
required

Employee-side inputs for a payroll calculation.

employer
EmployerInput · object
required

Employer-side inputs for a payroll calculation.

simulation
SimulationConfig · object
required

Simulation configuration: one or more salary scenarios.

options
CalculationOptions · object

Options that affect what the engine returns (not the calculation itself).

Response

Simulation results for all scenarios.

Multi-scenario simulation response. Results are never persisted.

id
string
required

Simulation ID (ULID). Not persisted — for correlation only.

country
string
required
scheme
string
required
year
integer
required
results
SimulationScenarioResult · object[]
required
dsl_version
string
required
computed_at
string<date-time>
required
status
string
default:success
Allowed value: "success"
is_simulation
boolean
default:true