Real vs Forecast Mode

Verso API supports two execution modes for payroll calculations: Real Mode and Forecast Mode. Understanding when to use each mode is essential for effective payroll management.

Mode Comparison

Real Mode

Real mode creates official payroll records that become part of the employee's permanent history.

When to Use

• Monthly payroll processing
• Final salary calculations
• Year-end reconciliation
• Official pay slip generation

Example

POST /payrolls/{payrollId}/cases (Real Mode)
 
{
  "userId": 7,
  "employeeId": 2,
  "divisionId": 3,
  "start": "2025-01-01T00:00:00Z",
  "remuneration": {
    "heuresTravaillees": 151.67,
    "tauxHoraire": 12.50
  }
}

Forecast Mode

Forecast mode runs simulations that are stored separately from official records, ideal for previews and what-if scenarios.

When to Use

• Employee net pay previews
• Bonus impact simulations
• Salary increase projections
• Benefits change calculations
• Testing before production

Example

POST /payrolls/{payrollId}/cases (Forecast Mode)
 
{
  "userId": 7,
  "employeeId": 2,
  "divisionId": 3,
  "forecast": "preview-jan2025-emp2",
  "start": "2025-01-01T00:00:00Z",
  "remuneration": {
    "heuresTravaillees": 151.67,
    "tauxHoraire": 12.50
  }
}

Forecast Identifier Strategies

Historized Forecasts

Create unique identifiers to keep multiple simulation versions:

Code
 
{
  "forecast": "salary-review.2025-01-15T10:30:00Z"
}

Use this approach when you need to:

• Compare multiple scenarios
• Track simulation history
• Audit forecast decisions

Ephemeral Forecasts

Reuse the same identifier to overwrite previous results:

Code
 
{
  "forecast": "current-preview"
}

Use this approach when you need to:

• Show real-time updates
• Minimize storage usage
• Display latest projection only

Workflow Example

Step 1: Simulate with Forecast

Forecast Payrun
 
{
  "name": "January_Preview",
  "payrunId": 3,
  "userId": 7,
  "forecast": "jan-2025-preview",
  "periodStart": "2025-01-01T00:00:00Z",
  "employeeIdentifiers": ["[email protected]"]
}

Step 2: Review Results

Check the simulation results and validate calculations.

Step 3: Run Real Payroll

Once validated, run the same calculation without the forecast field:

Real Payrun
 
{
  "name": "January_Official",
  "payrunId": 3,
  "userId": 7,
  "periodStart": "2025-01-01T00:00:00Z",
  "employeeIdentifiers": ["[email protected]"]
}

Data Isolation

Forecast and Real data are completely isolated:

Code
 
┌─────────────────────────────────────┐
│           Database                   │
│  ┌───────────────┐ ┌──────────────┐ │
│  │  Real Data    │ │ Forecast Data│ │
│  │               │ │              │ │
│  │ • Official    │ │ • Simulations│ │
│  │ • Permanent   │ │ • Temporary  │ │
│  │ • Auditable   │ │ • Isolated   │ │
│  └───────────────┘ └──────────────┘ │
└─────────────────────────────────────┘

Use Case: Employee Self-Service

Code
 
Employee Portal Flow:
1. Employee enters expected hours/overtime
2. API runs forecast calculation
3. Employee sees projected net pay
4. HR runs official payroll later

Next Steps

• Quickstart - Complete payroll workflow
• Case Fields Reference - Available input fields
• Error Handling - Handling API errors