Verso is an embedded payroll API platform designed for European markets. It enables you to integrate comprehensive payroll calculations directly into your applications, handling everything from employee management to detailed pay slip generation.
Key Capabilities
Verso API provides a complete payroll solution through four main components:
| Component | Description |
|---|---|
| Users | Create users who can manage payroll operations |
| Employees | Create and manage employee records with division assignments |
| Cases | Define payroll variables (salary, hours, allowances, deductions) |
| Payruns | Execute payroll calculations for one or multiple employees |
| Results | Retrieve detailed pay slip data with wage type breakdowns |
Real vs Forecast Mode
Verso API supports two execution modes:
- Real Mode: Payroll calculations are persisted and become part of official records
- Forecast Mode: Run simulations that are stored separately from official records, ideal for "what-if" scenarios and previews
Use Forecast Mode to let employees preview their expected net pay before the official payroll run. This reduces payroll queries and improves transparency.
Getting Started
1. Access the Sandbox
The sandbox environment allows you to test all API features without affecting production data. Contact your account manager to obtain your sandbox credentials.
2. Authenticate
All API requests require authentication. Include your API key in the request headers:
Authentication Header
3. Explore the Documentation
| Resource | Description |
|---|---|
| Interactive API Reference | Try API calls directly in your browser |
Complete Payroll Forecast Example
Here's a complete workflow to run a forecast payroll simulation from scratch. The forecast field links case values to a specific simulation run, stored separately from official payroll records.
Step 1: Create a User
First, create a user who will manage payroll operations:
POST /users
Response includes the userId (e.g., 7).
Step 2: Create an Employee
Create an employee and assign them to a division:
POST /employees
Response includes the employeeId (e.g., 2).
Step 3: Add Employee Case Values (Forecast)
Add all employee payroll data in a single call using relatedCases. Use the forecast field to mark this as a simulation:
POST /payrolls/{payrollId}/cases
- Use
relatedCasesto group multiple case types (Identity, Remuneration, Expenses, Tax, Insurance) in a single API call - The
forecastfield creates a unique simulation namespace - results are stored and retrievable Regularisationallows salary adjustments (positive or negative) that appear on the pay slip
Step 4: Start the Payrun Job (Forecast)
Launch the forecast payroll calculation using the same forecast identifier:
POST /payruns/jobs
Response includes the payrunJobId (e.g., 8) and job status:
Code
Step 5: Get Detailed Results
Retrieve the complete wage type breakdown:
GET /payrollresults/sets?payrunJobId=8
Response includes all calculated wage types:
Code
API Endpoints Summary
| Step | Method | Endpoint | Purpose |
|---|---|---|---|
| 1 | POST | /users | Create a user |
| 2 | POST | /employees | Create an employee with division |
| 3 | POST | /payrolls/{id}/cases | Add all case values (with forecast) |
| 4 | POST | /payruns/jobs | Start payrun calculation (with forecast) |
| 5 | GET | /payrollresults/sets?payrunJobId={id} | Get wage type details |
Case Fields Reference
| Case | Field | Type | Description |
|---|---|---|---|
| Remuneration | HeuresTravaillees | Decimal | Hours worked in the period |
| Remuneration | TauxHoraire | Money | Hourly rate |
| Frais | NombreRepas | Decimal | Number of meal allowances |
| Frais | MontantRepas | Money | Amount per meal |
| Frais | IndemniteKilometrique | Money | Mileage allowance |
| Frais | Regularisation | Money | Net salary adjustment (+/-) |
| PAS | TauxPAS | Percent | Withholding tax rate |
| PrevoyanceMutuelle | MutuelleObligatoire | Money | Mandatory health insurance |
| PrevoyanceMutuelle | MutuelleFacultative | Money | Optional health insurance |
| PrevoyanceMutuelle | TauxPrevoyance | Percent | Social security rate |