Skip to main content
POST
Simulate multiple salary scenarios (not persisted)

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