Quickstart

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:

• Partner Account: Your Partner ID provided by Verso (e.g., 5)
• API Key: Bearer token linked to your Partner ID
• Tenant Registration: You've registered at least one tenant (see Authentication)
• HTTP Client: cURL, Postman, or any REST client

Example identifiers used in this guide:

• Partner ID: 5
• Tenant ID: 10
• Division ID: 3 (provided with credentials)
• Payroll ID: 3 (provided with credentials)

Complete Workflow

Step 0: Register a Tenant

First, register a new tenant (client) to your partner account:

Register a Tenant
 
curl -X POST "https://api.versohq.io/partners/5/tenants" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tenantId": 10,
    "externalId": "my-client-abc"
  }'

Response:

Code
 
{
  "id": 1,
  "partnerId": 5,
  "tenantId": 10,
  "externalId": "my-client-abc",
  "created": "2026-01-07T10:00:00Z"
}

Step 1: Create a User

Create a user who will manage payroll operations:

Create User
 
curl -X POST "https://api.versohq.io/partners/5/tenants/10/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.versohq.io/partners/5/tenants/10/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.versohq.io/partners/5/tenants/10/payrolls/3/cases" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": 7,
    "employeeId": 2,
    "divisionId": 3,
    "forecast": "quickstart-test",
    "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.versohq.io/partners/5/tenants/10/payruns/jobs" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Payrun_Jan2025",
    "payrunId": 3,
    "userId": 7,
    "forecast": "quickstart-test",
    "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.versohq.io/partners/5/tenants/10/payrollresults/sets?payrunJobId=8" \
  -H "Authorization: Bearer YOUR_API_KEY"

Code
 
# Fetch 50 results at a time
curl -X GET "https://api.versohq.io/partners/5/tenants/10/payrollresults/sets?payrunJobId=8&top=50&skip=0"
curl -X GET "https://api.versohq.io/partners/5/tenants/10/payrollresults/sets?payrunJobId=8&top=50&skip=50"
# ... continue until all results are fetched

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 }
  ]
}

Key Results:

• SalaireBase (100): Gross salary = 151.67 hours × 12.50 €/hour = 1,895.88 €
• TotalCotisationsSalariales (910): Employee social contributions deducted from salary
• TotalCotisationsPatronales (920): Employer social contributions (paid by company)
• NetAPayer (990): Final net salary to pay the employee: 1,862.45 €

Workflow Summary

Next Steps

• Authentication - Learn about API authentication methods
• Case Fields Reference - Complete list of available fields
• Real vs Forecast Mode - Learn when to use forecast for testing vs real mode for production
• API Reference - Explore all available endpoints