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": {
    "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",
    "num_dependentes_irrf": 0,
    "vale_transporte_amount": "0",
    "pensao_alimenticia_amount": "0",
    "decimo_terceiro_amount": "0",
    "ferias_amount": "0",
    "rat_fap_rate": "0.02",
    "cantidad_hijos": 0,
    "cantidad_hijos_incapacitados": 0,
    "cuota_sindical_rate": "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
}

Payroll

Simulate multiple salary scenarios (not persisted)

Run payroll calculations for multiple salary scenarios without persisting results.

Intended for quote/preview UIs, HR tools, and compensation planning:

“What will my total employer cost be if I hire at X salary?”
“Show me the ISR impact of a 20% raise vs. a 40% raise.”

Important: simulation results are NOT payroll records. They are never stored and do not appear in any reports or audit logs. The response includes is_simulation: true as an explicit flag.

Supports 1–20 scenarios per request. Each scenario can vary salary and enable/disable optional perceptions independently.

POST

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": {
    "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",
    "num_dependentes_irrf": 0,
    "vale_transporte_amount": "0",
    "pensao_alimenticia_amount": "0",
    "decimo_terceiro_amount": "0",
    "ferias_amount": "0",
    "rat_fap_rate": "0.02",
    "cantidad_hijos": 0,
    "cantidad_hijos_incapacitados": 0,
    "cuota_sindical_rate": "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:

Results are NEVER persisted
Supports multiple scenarios in a single request
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.

Show child attributes

employee

EmployeeInput · object

required

Employee-side inputs for a payroll calculation.

Show child attributes

employer

EmployerInput · object

required

Employer-side inputs for a payroll calculation.

Show child attributes

simulation

SimulationConfig · object

required

Simulation configuration: one or more salary scenarios.

Show child attributes

options

CalculationOptions · object

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

Show child attributes

Response

Simulation results for all scenarios.

Multi-scenario simulation response. Results are never persisted.

string

required

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

country

string

required

scheme

string

required

year

integer

required

results

SimulationScenarioResult · object[]

required

Show child attributes

dsl_version

string

required

computed_at

string<date-time>

required

status

string

default:success

Allowed value: "success"

is_simulation

boolean

default:true

Calculate payroll for multiple employees List payouts (mock)