Getting Started

Quickstart

Copy page

Get started with Verso API by running a complete payroll calculation. This guide walks you through the entire workflow from user creation to retrieving detailed pay results.

Prerequisites

Before you begin, ensure you have:

• Sandbox API Key: Contact your account manager to obtain credentials
• HTTP Client: cURL, Postman, or any REST client
• Division ID: Your tenant's division identifier (provided with credentials)
• Payroll ID: Your payroll configuration identifier (provided with credentials)

Complete Workflow

Step 1: Create a User

Create a user who will manage payroll operations:

Create User
 
curl -X POST "https://api.sandbox.verso.io/users" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "[email protected]",
    "firstName": "Support",
    "lastName": "Admin",
    "culture": "fr-FR",
    "userType": "User"
  }'

Response:

Code
 
{
  "id": 7,
  "identifier": "[email protected]",
  "firstName": "Support",
  "lastName": "Admin"
}

Save the id value (e.g., 7) for subsequent requests.

Step 2: Create an Employee

Create an employee and assign them to a division:

Create Employee
 
curl -X POST "https://api.sandbox.verso.io/employees" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "[email protected]",
    "firstName": "Jean",
    "lastName": "Dupont",
    "culture": "fr-FR",
    "divisions": ["MainDivision"]
  }'

Response:

Code
 
{
  "id": 2,
  "identifier": "[email protected]",
  "firstName": "Jean",
  "lastName": "Dupont"
}

Save the id value (e.g., 2) for subsequent requests.

Step 3: Add Employee Case Values

Add all payroll data for the employee using the simplified flat format:

Add Case Values
 
curl -X POST "https://api.sandbox.verso.io/payrolls/3/cases" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": 7,
    "employeeId": 2,
    "divisionId": 3,
    "start": "2025-01-01T00:00:00Z",
    "identite": {
      "nom": "Dupont",
      "prenom": "Jean"
    },
    "remuneration": {
      "heuresTravaillees": 151.67,
      "tauxHoraire": 12.50
    },
    "frais": {
      "nombreRepas": 15,
      "montantRepas": 9.50,
      "indemniteKilometrique": 250,
      "regularisation": 50.00
    },
    "pas": {
      "tauxPAS": 0.05
    },
    "prevoyanceMutuelle": {
      "mutuelleObligatoire": 24.75,
      "mutuelleFacultative": 49.50,
      "tauxPrevoyance": 0.0089
    }
  }'

Step 4: Start the Payrun Job

Launch the payroll calculation:

Start Payrun
 
curl -X POST "https://api.sandbox.verso.io/payruns/jobs" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Payrun_Jan2025",
    "payrunId": 3,
    "userId": 7,
    "periodStart": "2025-01-01T00:00:00Z",
    "reason": "January 2025 payroll",
    "employeeIdentifiers": ["[email protected]"]
  }'

Response:

Code
 
{
  "id": 8,
  "name": "Payrun_Jan2025",
  "jobStatus": "Draft",
  "jobResult": "Full",
  "periodStart": "2025-01-01T00:00:00Z",
  "periodEnd": "2025-01-31T23:59:59.9999999Z",
  "totalEmployeeCount": 1,
  "processedEmployeeCount": 1,
  "message": "Completed payrun calculation successfully"
}

Save the id value (e.g., 8) for retrieving results.

Step 5: Get Detailed Results

Retrieve the complete wage type breakdown:

Get Results
 
curl -X GET "https://api.sandbox.verso.io/payrollresults/sets?payrunJobId=8" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

Code
 
{
  "wageTypeResults": [
    { "wageTypeNumber": 100, "wageTypeName": "SalaireBase", "value": 1895.88 },
    { "wageTypeNumber": 600, "wageTypeName": "IndemniteRepas", "value": 142.5 },
    { "wageTypeNumber": 620, "wageTypeName": "IndemniteKilometrique", "value": 250.0 },
    { "wageTypeNumber": 650, "wageTypeName": "Regularisation", "value": 50.0 },
    { "wageTypeNumber": 910, "wageTypeName": "TotalCotisationsSalariales", "value": 475.12 },
    { "wageTypeNumber": 920, "wageTypeName": "TotalCotisationsPatronales", "value": 743.89 },
    { "wageTypeNumber": 930, "wageTypeName": "TotalAllegements", "value": -520.45 },
    { "wageTypeNumber": 950, "wageTypeName": "NetImposable", "value": 1550.32 },
    { "wageTypeNumber": 980, "wageTypeName": "TotalIndemnites", "value": 442.5 },
    { "wageTypeNumber": 990, "wageTypeName": "NetAPayer", "value": 1862.45 }
  ]
}

Workflow 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
4	POST	/payruns/jobs	Start payrun calculation
5	GET	/payrollresults/sets?payrunJobId={id}	Get wage type details

Next Steps

• Authentication - Learn about API authentication methods
• Case Fields Reference - Complete list of available fields
• API Reference - Explore all available endpoints