Copy page

Guides

Contribution Catalogue

The Contribution Catalogue lets you inspect the structure and rates of social contributions without triggering a payroll calculation. This is useful for building UI previews, validating rate configurations, or understanding the regulation schema.

Overview

The catalogue exposes two complementary resources:

Resource	Endpoint	What it returns
Wage Type Definitions	GET /payrolls/{payrollId}/wagetypes	Contribution structure with static attributes
Lookup Tables	GET /regulations/{regulationId}/lookups	Rate tables (e.g., URSSAF, Retraite, CSG-CRDS)
Lookup Entries	GET /regulations/{regulationId}/lookups/{lookupId}/values	Individual rate key-value pairs

Step 1: Read the Contribution Catalogue

Retrieve all wage type definitions for a payroll. Each definition includes static attributes that describe its role in the payroll calculation.

Code
GET /partners/{partnerId}/tenants/{tenantId}/payrolls/{payrollId}/wagetypes

Example Response

Code
[
  {
    "id": 42,
    "wageTypeNumber": 210,
    "name": "Maladie salariale",
    "attributes": {
      "part": "salariale",
      "categorie": "cotisation",
      "lookupName": "TauxURSSAF",
      "lookupKey": "maladie_salarial",
      "plafondRef": "none"
    }
  },
  {
    "id": 55,
    "wageTypeNumber": 300,
    "name": "Vieillesse plafonnée salariale",
    "attributes": {
      "part": "salariale",
      "categorie": "cotisation",
      "lookupName": "TauxURSSAF",
      "lookupKey": "vieillesse_plafonnee_salarial",
      "plafondRef": "PlafondSS"
    }
  },
  {
    "id": 71,
    "wageTypeNumber": 402,
    "name": "AGIRC-ARRCO T1 salariale",
    "attributes": {
      "part": "salariale",
      "categorie": "cotisation",
      "lookupName": "TauxRetraite",
      "lookupKey": "agirc_arrco_t1_salarial",
      "plafondRef": "PlafondSS"
    }
  }
]

Attribute Schema

Attribute	Description	Example values
part	Employee or employer share	salariale, patronale
categorie	Contribution category	cotisation, base, plafond, net
lookupName	Rate table name	TauxURSSAF, TauxRetraite, TauxCSGCRDS
lookupKey	Key within the rate table	maladie_salarial, vieillesse_plafonnee_salarial
plafondRef	Ceiling reference	PlafondSS, none

Step 2: Resolve Rate Values

Use the lookup endpoints to retrieve the actual rate values referenced by wage type attributes.

List Available Lookup Tables

Code
GET /partners/{partnerId}/tenants/{tenantId}/regulations/{regulationId}/lookups

Code
[
  { "id": 1, "name": "TauxURSSAF", "description": "URSSAF contribution rates" },
  { "id": 2, "name": "TauxRetraite", "description": "Complementary pension rates" },
  { "id": 3, "name": "TauxCSGCRDS", "description": "CSG and CRDS rates" }
]

Get Entries for a Specific Table

Code
GET /partners/{partnerId}/tenants/{tenantId}/regulations/{regulationId}/lookups/1/values

Code
[
  { "key": "maladie_salarial", "value": "0" },
  { "key": "maladie_patronal", "value": "0.07" },
  { "key": "vieillesse_plafonnee_salarial", "value": "0.069" },
  { "key": "vieillesse_plafonnee_patronal", "value": "0.0855" },
  { "key": "vieillesse_deplafonnee_salarial", "value": "0.004" },
  { "key": "vieillesse_deplafonnee_patronal", "value": "0.0202" }
]

Resolving a Rate

To find the rate for WT 300 — Vieillesse plafonnée salariale:

1. Read its attributes: lookupName: "TauxURSSAF", lookupKey: "vieillesse_plafonnee_salarial"
2. Find the lookup table named TauxURSSAF (id: 1)
3. Query its values and find key vieillesse_plafonnee_salarial → "0.069" (6.9%)

Catalogue vs Simulation

Aspect	Catalogue	Simulation (Payrun)
Purpose	Browse structure and reference rates	Calculate actual amounts
Triggers calculation	No	Yes
Returns amounts	No (rates only)	Yes (computed values)
Use case	UI scaffolding, rate preview, configuration audit	Pay slip generation, what-if scenarios
Performance	Instant (no computation)	Depends on employee count

Use the catalogue to build contribution overviews and validate rate configurations. Use simulations (via payrun jobs) when you need actual computed amounts for specific employees.

Next Steps

• Quickstart — Run your first payroll simulation
• Case Fields Reference — Employee input variables
• API Reference — Full endpoint documentation