Getting Started

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.

Route Pattern

All API endpoints use the Partner route pattern: /partners/{partnerId}/tenants/{tenantId}/{resource}. See Authentication for details.

Multi-Tenant Architecture

You can manage multiple tenants (clients) using the same API key. Simply change the tenantId in the URL to switch between clients. Each tenant's data is completely isolated.

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
HTTP Client: cURL, Postman, or any REST client

Environment Discovery

After creating your tenant (Step 1), Step 2 shows how to discover your actual division, payroll, and payrun IDs.

Example identifiers used in this guide:

Partner ID: 5
Tenant ID: 10
Division ID: 3 (discovered in Step 2)
Payroll ID: 3 (discovered in Step 2)

First Time Setup

Step 1 shows how to register a tenant to your partner account. This is only needed once per client - after that, you can skip to Step 3 for subsequent payruns.

Download our Postman Collection to test the complete workflow with pre-configured requests.

Complete Workflow

Step 1: Create a Tenant

Create a minimal PayrollEngine tenant for the client. externalId is your stable dossier ID and makes the request idempotent; Verso generates the internal PayrollEngine identifier.

Code
curl -X POST "https://api.versohq.io/partners/5/tenants" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "my-client-abc",
    "name": "My client",
    "culture": "fr-FR"
  }'

Response:


Code
{
  "id": 1,
  "partnerId": 5,
  "tenantId": 42,
  "tenantIdentifier": "partner-5-550e8400e29b41d4a716446655440000",
  "externalId": "my-client-abc",
  "name": "My client",
  "culture": "fr-FR",
  "status": "active",
  "created": "2026-01-07T10:00:00Z"
}

This endpoint creates a bare tenant only: no employee, payroll, regulation or DSN configuration is provisioned. For a complete French SASU mandataire dossier, use POST /partners/{partnerId}/tenants/mandataires. Reusing the same externalId returns the same tenant.

Step 2: Discover Your Environment

After registering your tenant, discover the IDs you'll need for subsequent steps:

Code
curl -X GET "https://api.versohq.io/partners/5/tenants/10/divisions" \
  -H "Authorization: Bearer YOUR_API_KEY"

Save the id and name of your target division.

Code
curl -X GET "https://api.versohq.io/partners/5/tenants/10/payrolls" \
  -H "Authorization: Bearer YOUR_API_KEY"

Save the id of your payroll.

Code
curl -X GET "https://api.versohq.io/partners/5/tenants/10/payruns" \
  -H "Authorization: Bearer YOUR_API_KEY"

Save the id of your payrun (e.g., 3). You'll need it when starting payrun jobs in Step 6.

Step 3: Create a User

Create a user who will manage payroll operations:

Code
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 4: Create an Employee

Create an employee and assign them to a division:

Code
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": ["{divisionName}"]
  }'

Response:


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

Replace {divisionName} with the division name discovered in Step 2.

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

Step 5: Add Employee Case Values

Add all payroll data for the employee using the native CaseChangeSetup format. The payload uses a nested structure: a root case with its values, and relatedCases for additional domains (remuneration, expenses, etc.).

Code
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",
    "case": {
      "caseName": "Identite",
      "values": [
        { "caseFieldName": "Nom", "value": "Dupont", "start": "2025-01-01T00:00:00Z" },
        { "caseFieldName": "Prenom", "value": "Jean", "start": "2025-01-01T00:00:00Z" }
      ],
      "relatedCases": [
        {
          "caseName": "Remuneration",
          "values": [
            { "caseFieldName": "HeuresTravaillees", "value": "151.67", "start": "2025-01-01T00:00:00Z" },
            { "caseFieldName": "TauxHoraire", "value": "12.50", "start": "2025-01-01T00:00:00Z" }
          ]
        },
        {
          "caseName": "Frais",
          "values": [
            { "caseFieldName": "NombreRepas", "value": "15", "start": "2025-01-01T00:00:00Z" },
            { "caseFieldName": "MontantRepas", "value": "9.50", "start": "2025-01-01T00:00:00Z" },
            { "caseFieldName": "IndemniteKilometrique", "value": "250", "start": "2025-01-01T00:00:00Z" },
            { "caseFieldName": "Regularisation", "value": "50.00", "start": "2025-01-01T00:00:00Z" }
          ]
        },
        {
          "caseName": "PAS",
          "values": [
            { "caseFieldName": "TauxPAS", "value": "0.05", "start": "2025-01-01T00:00:00Z" }
          ]
        },
        {
          "caseName": "PrevoyanceMutuelle",
          "values": [
            { "caseFieldName": "MutuelleObligatoire", "value": "24.75", "start": "2025-01-01T00:00:00Z" },
            { "caseFieldName": "MutuelleFacultative", "value": "49.50", "start": "2025-01-01T00:00:00Z" },
            { "caseFieldName": "TauxPrevoyance", "value": "0.0089", "start": "2025-01-01T00:00:00Z" }
          ]
        }
      ]
    }
  }'

Response (201 Created):


Code
{
  "id": 15,
  "userId": 7,
  "employeeId": 2,
  "divisionId": 3
}

Forecast Mode

The forecast field is set at the root level of the payload (not inside case). It runs a simulation without affecting official payroll records. Remove this field when running real payroll. See Real vs Forecast Mode.

Step 6: Start the Payrun Job

Payrun and user lookup

The launch request uses the exact payrunName and userIdentifier returned by GET /payruns and GET /users. Match those resources by the IDs created during setup; do not select the first item in a multi-tenant collection.

Launch the payroll calculation:

Code
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",
    "payrunName": "Monthly",
    "userIdentifier": "[email protected]",
    "forecast": "quickstart-test",
    "periodStart": "2025-01-01T00:00:00Z",
    "reason": "January 2025 payroll",
    "employeeIdentifiers": ["[email protected]"]
  }'

Response (202 Accepted):


Code
{
  "id": 8,
  "name": "Payrun_Jan2025",
  "jobStatus": "Process",
  "jobResult": "Full",
  "periodStart": "2025-01-01T00:00:00Z",
  "periodEnd": "2025-01-31T23:59:59.9999999Z",
  "totalEmployeeCount": 1,
  "processedEmployeeCount": 0,
  "message": "Payrun job queued for background processing"
}

Save the id value (e.g., 8). The job runs asynchronously — poll its status until it completes:

Code
curl -X GET "https://api.versohq.io/partners/5/tenants/10/payruns/jobs/8" \
  -H "Authorization: Bearer YOUR_API_KEY"

Wait until jobEnd is set (or jobStatus is Forecast/Complete) before retrieving results. Upstream v1.0.1 can return a successfully calculated asynchronous job to Draft, so Draft without jobEnd is still queued or running. Treat Abort and Cancel as failures.

Job completion and result persistence are two separate asynchronous boundaries. After the job is terminal, retry the exact payrunJobId query with bounded backoff until it returns a result set. Do this after every recalculation before reading a summary or running DSN control; an empty 200 response is transient and must never be replaced with a result from another job.

Step 7: Get Detailed Results

Retrieve the complete wage type breakdown:

Code
curl -X GET "https://api.versohq.io/partners/5/tenants/10/payrollresults/sets?payrunJobId=8" \
  -H "Authorization: Bearer YOUR_API_KEY"

Pagination for Large Batches

For payrun jobs with many employees (100+), use pagination to avoid timeouts:

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 (array of result sets):


Code
[
  {
    "wageTypeResults": [
      { "wageTypeNumber": 100, "wageTypeName": "SalaireBase", "value": 1895.88 },
      { "wageTypeNumber": 600, "wageTypeName": "IndemniteRepas", "value": 142.5 },
      { "wageTypeNumber": 611, "wageTypeName": "IndemniteKilometrique", "value": 250.0 },
      { "wageTypeNumber": 650, "wageTypeName": "Regularisation", "value": 50.0 },
      { "wageTypeNumber": 900, "wageTypeName": "TotalBrut", "value": 2338.38 },
      { "wageTypeNumber": 910, "wageTypeName": "TotalCotisationsSalariales", "value": 395.11 },
      { "wageTypeNumber": 920, "wageTypeName": "TotalCotisationsPatronales", "value": 701.78 },
      { "wageTypeNumber": 930, "wageTypeName": "TotalAllegements", "value": -531.00 },
      { "wageTypeNumber": 950, "wageTypeName": "NetImposable", "value": 1627.43 },
      { "wageTypeNumber": 960, "wageTypeName": "PAS", "value": 81.37 },
      { "wageTypeNumber": 980, "wageTypeName": "TotalIndemnites", "value": 442.5 },
      { "wageTypeNumber": 990, "wageTypeName": "NetAPayer", "value": 1861.90 }
    ],
    "collectorResults": [ ... ],
    "payrunResults": [ ... ]
  }
]

Key Results:

SalaireBase (100): Gross salary = 151.67 hours × 12.50 €/hour = 1,895.88 €
TotalBrut (900): Total gross including allowances = 2,338.38 €
TotalCotisationsSalariales (910): Employee social contributions = 395.11 €
TotalCotisationsPatronales (920): Employer social contributions = 701.78 €
PAS (960): Withholding tax (5% of net imposable) = 81.37 €
NetAPayer (990): Final net salary to pay the employee: 1,861.90 €

Workflow Summary

Step	Method	Endpoint	Purpose
1	POST	`/partners/{partnerId}/tenants`	Register a tenant
2	GET	`/divisions`, `/payrolls`, `/payruns`	Discover environment IDs
3	POST	`/partners/{partnerId}/tenants/{tenantId}/users`	Create a user
4	POST	`/partners/{partnerId}/tenants/{tenantId}/employees`	Create an employee with division
5	POST	`/partners/{partnerId}/tenants/{tenantId}/payrolls/{id}/cases`	Add case values (native CaseChangeSetup format)
6	POST	`/partners/{partnerId}/tenants/{tenantId}/payruns/jobs`	Start payrun calculation
6b	GET	`/partners/{partnerId}/tenants/{tenantId}/payruns/jobs/{jobId}`	Poll job status until complete
7	GET	`/partners/{partnerId}/tenants/{tenantId}/payrollresults/sets?payrunJobId={id}`	Get wage type details

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

Last modified on August 2, 2026

Introduction Authentication

Getting Started

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.

Route Pattern

All API endpoints use the Partner route pattern: /partners/{partnerId}/tenants/{tenantId}/{resource}. See Authentication for details.

Multi-Tenant Architecture

You can manage multiple tenants (clients) using the same API key. Simply change the tenantId in the URL to switch between clients. Each tenant's data is completely isolated.

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
HTTP Client: cURL, Postman, or any REST client

Environment Discovery

After creating your tenant (Step 1), Step 2 shows how to discover your actual division, payroll, and payrun IDs.

Example identifiers used in this guide:

Partner ID: 5
Tenant ID: 10
Division ID: 3 (discovered in Step 2)
Payroll ID: 3 (discovered in Step 2)

First Time Setup

Step 1 shows how to register a tenant to your partner account. This is only needed once per client - after that, you can skip to Step 3 for subsequent payruns.

Download our Postman Collection to test the complete workflow with pre-configured requests.

Complete Workflow

Step 1: Create a Tenant

Create a minimal PayrollEngine tenant for the client. externalId is your stable dossier ID and makes the request idempotent; Verso generates the internal PayrollEngine identifier.

Code
curl -X POST "https://api.versohq.io/partners/5/tenants" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "my-client-abc",
    "name": "My client",
    "culture": "fr-FR"
  }'

Response:


Code
{
  "id": 1,
  "partnerId": 5,
  "tenantId": 42,
  "tenantIdentifier": "partner-5-550e8400e29b41d4a716446655440000",
  "externalId": "my-client-abc",
  "name": "My client",
  "culture": "fr-FR",
  "status": "active",
  "created": "2026-01-07T10:00:00Z"
}

Step 2: Discover Your Environment

After registering your tenant, discover the IDs you'll need for subsequent steps:

Code
curl -X GET "https://api.versohq.io/partners/5/tenants/10/divisions" \
  -H "Authorization: Bearer YOUR_API_KEY"

Save the id and name of your target division.

Code
curl -X GET "https://api.versohq.io/partners/5/tenants/10/payrolls" \
  -H "Authorization: Bearer YOUR_API_KEY"

Save the id of your payroll.

Code
curl -X GET "https://api.versohq.io/partners/5/tenants/10/payruns" \
  -H "Authorization: Bearer YOUR_API_KEY"

Save the id of your payrun (e.g., 3). You'll need it when starting payrun jobs in Step 6.

Step 3: Create a User

Create a user who will manage payroll operations:

Code
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 4: Create an Employee

Create an employee and assign them to a division:

Code
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": ["{divisionName}"]
  }'

Response:


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

Replace {divisionName} with the division name discovered in Step 2.

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

Step 5: Add Employee Case Values

Code
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",
    "case": {
      "caseName": "Identite",
      "values": [
        { "caseFieldName": "Nom", "value": "Dupont", "start": "2025-01-01T00:00:00Z" },
        { "caseFieldName": "Prenom", "value": "Jean", "start": "2025-01-01T00:00:00Z" }
      ],
      "relatedCases": [
        {
          "caseName": "Remuneration",
          "values": [
            { "caseFieldName": "HeuresTravaillees", "value": "151.67", "start": "2025-01-01T00:00:00Z" },
            { "caseFieldName": "TauxHoraire", "value": "12.50", "start": "2025-01-01T00:00:00Z" }
          ]
        },
        {
          "caseName": "Frais",
          "values": [
            { "caseFieldName": "NombreRepas", "value": "15", "start": "2025-01-01T00:00:00Z" },
            { "caseFieldName": "MontantRepas", "value": "9.50", "start": "2025-01-01T00:00:00Z" },
            { "caseFieldName": "IndemniteKilometrique", "value": "250", "start": "2025-01-01T00:00:00Z" },
            { "caseFieldName": "Regularisation", "value": "50.00", "start": "2025-01-01T00:00:00Z" }
          ]
        },
        {
          "caseName": "PAS",
          "values": [
            { "caseFieldName": "TauxPAS", "value": "0.05", "start": "2025-01-01T00:00:00Z" }
          ]
        },
        {
          "caseName": "PrevoyanceMutuelle",
          "values": [
            { "caseFieldName": "MutuelleObligatoire", "value": "24.75", "start": "2025-01-01T00:00:00Z" },
            { "caseFieldName": "MutuelleFacultative", "value": "49.50", "start": "2025-01-01T00:00:00Z" },
            { "caseFieldName": "TauxPrevoyance", "value": "0.0089", "start": "2025-01-01T00:00:00Z" }
          ]
        }
      ]
    }
  }'

Response (201 Created):


Code
{
  "id": 15,
  "userId": 7,
  "employeeId": 2,
  "divisionId": 3
}

Forecast Mode

Step 6: Start the Payrun Job

Payrun and user lookup

Launch the payroll calculation:

Code
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",
    "payrunName": "Monthly",
    "userIdentifier": "[email protected]",
    "forecast": "quickstart-test",
    "periodStart": "2025-01-01T00:00:00Z",
    "reason": "January 2025 payroll",
    "employeeIdentifiers": ["[email protected]"]
  }'

Response (202 Accepted):


Code
{
  "id": 8,
  "name": "Payrun_Jan2025",
  "jobStatus": "Process",
  "jobResult": "Full",
  "periodStart": "2025-01-01T00:00:00Z",
  "periodEnd": "2025-01-31T23:59:59.9999999Z",
  "totalEmployeeCount": 1,
  "processedEmployeeCount": 0,
  "message": "Payrun job queued for background processing"
}

Save the id value (e.g., 8). The job runs asynchronously — poll its status until it completes:

Code
curl -X GET "https://api.versohq.io/partners/5/tenants/10/payruns/jobs/8" \
  -H "Authorization: Bearer YOUR_API_KEY"

Step 7: Get Detailed Results

Retrieve the complete wage type breakdown:

Code
curl -X GET "https://api.versohq.io/partners/5/tenants/10/payrollresults/sets?payrunJobId=8" \
  -H "Authorization: Bearer YOUR_API_KEY"

Pagination for Large Batches

For payrun jobs with many employees (100+), use pagination to avoid timeouts:

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 (array of result sets):


Code
[
  {
    "wageTypeResults": [
      { "wageTypeNumber": 100, "wageTypeName": "SalaireBase", "value": 1895.88 },
      { "wageTypeNumber": 600, "wageTypeName": "IndemniteRepas", "value": 142.5 },
      { "wageTypeNumber": 611, "wageTypeName": "IndemniteKilometrique", "value": 250.0 },
      { "wageTypeNumber": 650, "wageTypeName": "Regularisation", "value": 50.0 },
      { "wageTypeNumber": 900, "wageTypeName": "TotalBrut", "value": 2338.38 },
      { "wageTypeNumber": 910, "wageTypeName": "TotalCotisationsSalariales", "value": 395.11 },
      { "wageTypeNumber": 920, "wageTypeName": "TotalCotisationsPatronales", "value": 701.78 },
      { "wageTypeNumber": 930, "wageTypeName": "TotalAllegements", "value": -531.00 },
      { "wageTypeNumber": 950, "wageTypeName": "NetImposable", "value": 1627.43 },
      { "wageTypeNumber": 960, "wageTypeName": "PAS", "value": 81.37 },
      { "wageTypeNumber": 980, "wageTypeName": "TotalIndemnites", "value": 442.5 },
      { "wageTypeNumber": 990, "wageTypeName": "NetAPayer", "value": 1861.90 }
    ],
    "collectorResults": [ ... ],
    "payrunResults": [ ... ]
  }
]

Key Results:

SalaireBase (100): Gross salary = 151.67 hours × 12.50 €/hour = 1,895.88 €
TotalBrut (900): Total gross including allowances = 2,338.38 €
TotalCotisationsSalariales (910): Employee social contributions = 395.11 €
TotalCotisationsPatronales (920): Employer social contributions = 701.78 €
PAS (960): Withholding tax (5% of net imposable) = 81.37 €
NetAPayer (990): Final net salary to pay the employee: 1,861.90 €

Workflow Summary

Step	Method	Endpoint	Purpose
1	POST	`/partners/{partnerId}/tenants`	Register a tenant
2	GET	`/divisions`, `/payrolls`, `/payruns`	Discover environment IDs
3	POST	`/partners/{partnerId}/tenants/{tenantId}/users`	Create a user
4	POST	`/partners/{partnerId}/tenants/{tenantId}/employees`	Create an employee with division
5	POST	`/partners/{partnerId}/tenants/{tenantId}/payrolls/{id}/cases`	Add case values (native CaseChangeSetup format)
6	POST	`/partners/{partnerId}/tenants/{tenantId}/payruns/jobs`	Start payrun calculation
6b	GET	`/partners/{partnerId}/tenants/{tenantId}/payruns/jobs/{jobId}`	Poll job status until complete
7	GET	`/partners/{partnerId}/tenants/{tenantId}/payrollresults/sets?payrunJobId={id}`	Get wage type details

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

Last modified on August 2, 2026

Introduction Authentication