# Case Fields Reference

:::tip[Dynamic Discovery]
Use `GET /payrolls/{payrollId}/cases/schema` to dynamically discover all available case fields as a JSON Schema. This endpoint returns field types, defaults, and localizations directly from the regulation — no userId or employeeId needed. Ideal for SDK generation and form building.
:::

:::note
The static reference below documents fields for the default Stairling regulation. For always-in-sync field definitions, prefer the `/cases/schema` endpoint above.
:::

This reference documents all available case fields for payroll calculations. Fields are organized by case name (domain) using the native `CaseChangeSetup` format.

## Payload Structure

When adding case values via `POST /payrolls/{payrollId}/cases`, use the `CaseChangeSetup` structure:

```json
{
  "userId": 7,
  "employeeId": 2,
  "divisionId": 3,
  "forecast": "optional-forecast-id",
  "case": {
    "caseName": "Identite",
    "values": [
      { "caseFieldName": "Nom", "value": "Dupont", "start": "2025-01-01T00:00:00Z" }
    ],
    "relatedCases": [
      {
        "caseName": "Remuneration",
        "values": [
          { "caseFieldName": "HeuresTravaillees", "value": "151.67", "start": "2025-01-01T00:00:00Z" }
        ]
      }
    ]
  }
}
```

**Key points:**
- `userId`, `employeeId`, `divisionId`, and `forecast` are at the **root level**
- The `case` object contains a `caseName`, its `values[]`, and optional `relatedCases[]`
- Each value entry requires `caseFieldName`, `value` (always a string), and `start` (ISO date)
- `relatedCases` follows the same structure recursively (caseName + values)

## Case Domains

### Identite (Identity)

Employee identification information.

| Field Name | Type | Description | Example |
|-----------|------|-------------|---------|
| `Nom` | string | Last name | `"Dupont"` |
| `Prenom` | string | First name | `"Jean"` |

**Example:**
```json
{
  "caseName": "Identite",
  "values": [
    { "caseFieldName": "Nom", "value": "Dupont", "start": "2025-01-01T00:00:00Z" },
    { "caseFieldName": "Prenom", "value": "Jean", "start": "2025-01-01T00:00:00Z" }
  ]
}
```

### Remuneration (Compensation)

Salary and hours worked.

| Field Name | Type | Description | Example |
|-----------|------|-------------|---------|
| `HeuresTravaillees` | number | Hours worked in the period | `"151.67"` |
| `TauxHoraire` | number | Hourly rate in euros | `"12.50"` |

**Example:**
```json
{
  "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" }
  ]
}
```

:::info[Calculation]
Base salary = `HeuresTravaillees` × `TauxHoraire`

Example: 151.67 × 12.50 = 1,895.88 €
:::

### Contrat (Employment Contract)

Employment contract information.

| Field Name | Type | Description | Example |
|-----------|------|-------------|---------|
| `DateDebutContrat` | date | Contract start date | `"2024-01-15"` |
| `DateFinContrat` | date | Contract end date (omit if ongoing) | `"2025-12-31"` |

**Example:**
```json
{
  "caseName": "Contrat",
  "values": [
    { "caseFieldName": "DateDebutContrat", "value": "2024-01-15", "start": "2025-01-01T00:00:00Z" }
  ]
}
```

### Frais (Expenses & Allowances)

Meal allowances, mileage, and adjustments.

| Field Name | Type | Description | Example |
|-----------|------|-------------|---------|
| `NombreRepas` | number | Number of meal allowances | `"15"` |
| `MontantRepas` | number | Amount per meal in euros | `"9.50"` |
| `IndemniteKilometrique` | number | Mileage allowance in euros | `"250"` |
| `Regularisation` | number | Net salary adjustment (+/-) | `"50.00"` |

**Example:**
```json
{
  "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" }
  ]
}
```

:::tip[Regularisation]
The `Regularisation` field allows positive or negative adjustments that appear directly on the payslip. Use it for:
- Expense reimbursements
- Salary corrections
- One-time bonuses
- Deductions
:::

### PAS (Withholding Tax)

French withholding tax (Prélèvement À la Source).

| Field Name | Type | Description | Example |
|-----------|------|-------------|---------|
| `TauxPAS` | number | Withholding tax rate (0-1) | `"0.05"` |

**Example:**
```json
{
  "caseName": "PAS",
  "values": [
    { "caseFieldName": "TauxPAS", "value": "0.05", "start": "2025-01-01T00:00:00Z" }
  ]
}
```

:::warning[Rate Format]
The `TauxPAS` must be a decimal between 0 and 1.
- 5% = `"0.05"`
- 15% = `"0.15"`
- 30% = `"0.30"`
:::

### PrevoyanceMutuelle (Benefits)

Health insurance and social security contributions.

| Field Name | Type | Description | Example |
|-----------|------|-------------|---------|
| `MutuelleObligatoire` | number | Mandatory health insurance (€) | `"24.75"` |
| `MutuelleFacultative` | number | Optional health insurance (€) | `"49.50"` |
| `TauxPrevoyance` | number | Social security rate (0-1) | `"0.0089"` |

**Example:**
```json
{
  "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" }
  ]
}
```

### Absences

Sick leave, work accidents, and unpaid leave.

| Field Name | Type | Description | Example |
|-----------|------|-------------|---------|
| `HeuresAbsenceMaladie` | number | Hours of sick leave | `"7"` |
| `TauxHoraireAbsence` | number | Hourly rate for absence valuation | `"11.88"` |
| `MontantAbsenceMaladie` | number | Total sick leave deduction amount | `"83.16"` |
| `MontantAbsenceATMP` | number | Total work accident deduction amount | `"0"` |
| `MontantAbsenceSansSolde` | number | Total unpaid leave deduction amount | `"0"` |

**Example:**
```json
{
  "caseName": "Absences",
  "values": [
    { "caseFieldName": "HeuresAbsenceMaladie", "value": "7", "start": "2025-01-01T00:00:00Z" },
    { "caseFieldName": "TauxHoraireAbsence", "value": "11.88", "start": "2025-01-01T00:00:00Z" },
    { "caseFieldName": "MontantAbsenceMaladie", "value": "83.16", "start": "2025-01-01T00:00:00Z" }
  ]
}
```

## Complete Example

```json title="POST /payrolls/{payrollId}/cases"
{
  "userId": 7,
  "employeeId": 2,
  "divisionId": 3,
  "forecast": "preview-jan2025-emp2",
  "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" }
        ]
      }
    ]
  }
}
```

## Quick Reference Table

| Case Name | Field Name | Type | Description |
|-----------|-----------|------|-------------|
| `Identite` | `Nom` | string | Last name |
| `Identite` | `Prenom` | string | First name |
| `Remuneration` | `HeuresTravaillees` | number | Hours worked |
| `Remuneration` | `TauxHoraire` | number | Hourly rate |
| `Contrat` | `DateDebutContrat` | date | Contract start date |
| `Contrat` | `DateFinContrat` | date | Contract end date |
| `Frais` | `NombreRepas` | number | Meal count |
| `Frais` | `MontantRepas` | number | Meal amount |
| `Frais` | `IndemniteKilometrique` | number | Mileage |
| `Frais` | `Regularisation` | number | Adjustment |
| `PAS` | `TauxPAS` | number | Tax rate |
| `PrevoyanceMutuelle` | `MutuelleObligatoire` | number | Mandatory insurance |
| `PrevoyanceMutuelle` | `MutuelleFacultative` | number | Optional insurance |
| `PrevoyanceMutuelle` | `TauxPrevoyance` | number | Prevoyance rate |
| `Absences` | `HeuresAbsenceMaladie` | number | Sick leave hours |
| `Absences` | `TauxHoraireAbsence` | number | Absence hourly rate |
| `Absences` | `MontantAbsenceMaladie` | number | Sick leave deduction |
| `Absences` | `MontantAbsenceATMP` | number | Work accident deduction |
| `Absences` | `MontantAbsenceSansSolde` | number | Unpaid leave deduction |

## Output: Wage Type Results

After running a payrun, you receive calculated wage types:

| Wage Type | Name | Description |
|-----------|------|-------------|
| 100 | SalaireBase | Base salary |
| 600 | IndemniteRepas | Meal allowance |
| 611 | IndemniteKilometrique | Mileage allowance |
| 650 | Regularisation | Salary adjustment |
| 900 | TotalBrut | Total gross salary |
| 910 | TotalCotisationsSalariales | Employee contributions |
| 920 | TotalCotisationsPatronales | Employer contributions |
| 930 | TotalAllegements | Tax credits |
| 950 | NetImposable | Taxable net income |
| 960 | PAS | Withholding tax |
| 980 | TotalIndemnites | Total allowances |
| 990 | NetAPayer | Net pay |

## Next Steps

- [Quickstart](/quickstart) - Complete workflow example
- [Real vs Forecast Mode](/guides/real-vs-forecast) - Execution modes
- [API Reference](/api) - All endpoints