> ## Documentation Index
> Fetch the complete documentation index at: https://code.dcycle.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Contracts & Remuneration
> Upload and manage employee demographics, contracts, and salary data for social sustainability reporting
## What is contract data?
Contract data captures the **employment relationship** between your organization and each employee. It includes:
* **Employee demographics**: birth date, gender, disability status
* **Contract details**: type (permanent/temporary), start and end dates, location, job category, working hours ratio
* **Remuneration**: gross annual salary including bonuses, allowances, and benefits
This data is the foundation for calculating **headcount**, **FTE**, **gender pay gap**, and **workforce composition** metrics in your social reports.
## Why is it needed?
Under **ESRS S1** and other sustainability reporting frameworks, organizations must disclose:
* Total number of employees by contract type, gender, and country
* Full-time vs part-time breakdown
* Employee turnover (new hires and departures)
* Remuneration gaps between genders and job categories
Without contract data, Dcycle cannot calculate these social KPIs for your reports.
## Data structure
Each CSV row represents **one employee with one contract and one remuneration period**. If an employee has had multiple contracts or salary changes, you include multiple rows with the same Employee ID.
```
EMPLOYEE (identified by External Employee ID)
|
+-- CONTRACT 1 (Jan 2024 - Jun 2024, Temporary)
| +-- REMUNERATION (Jan 2024 - Jun 2024, EUR 25,000)
|
+-- CONTRACT 2 (Jul 2024 - ongoing, Permanent)
+-- REMUNERATION (Jul 2024 - Dec 2024, EUR 32,000)
+-- REMUNERATION (Jan 2025 - ongoing, EUR 34,000)
```
Contracts for the same employee **cannot overlap** in dates. Similarly, remunerations within the same contract cannot overlap. The system enforces this automatically and will reject uploads with overlapping periods.
## CSV format
### Required columns
| Column | Type | Required | Description | Example |
| ---------------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------- |
| `external_employee_id` | String | Yes | Unique employee identifier from your HR system | `EMP001` |
| `birth_date` | Date | Yes | Employee's date of birth (YYYY-MM-DD) | `1990-05-15` |
| `gender` | String | Yes | `M` (Male), `F` (Female), `O` (Other), or `NS` (Not specified) | `F` |
| `disabled_employee` | String | Yes | Employee's recognized disability grade: `no_disability`, `with_disability`, `disability_33` (≥33%), or `disability_65` (≥65%). Common aliases are accepted (e.g. `33`, `33%`, `65`, `with disability`, `no disability`). | `disability_33` |
| Column | Type | Required | Description | Example |
| -------------------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------- | ------------- |
| `contract_type` | String | Yes | `permanent` or `temporary` | `permanent` |
| `contract_start_date` | Date | Yes | When the contract begins (YYYY-MM-DD) | `2024-01-01` |
| `contract_end_date` | Date | No | When the contract ends (empty if ongoing) | `2024-12-31` |
| `contract_end_date_reason` | String | No | Why the contract ended: `resignation`, `termination`, `change_of_contract`, `retirement`, or `fatality` | `resignation` |
| `location` | String | Yes | Country code where the employee works (ISO 2-letter, uppercase) | `ES` |
| `employment_category` | String | Yes | Job category or professional classification | `Engineer` |
| `working_hours_ratio` | Decimal | Yes | FTE ratio: `1.0` for full-time, `0.5` for half-time, etc. | `1.0` |
| `labor_agreement` | Boolean | Yes | Whether the employee is covered by a collective bargaining agreement | `true` |
| Column | Type | Required | Description | Example |
| ------------------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------ |
| `remuneration_amount` | Decimal | No | Annual gross salary including bonuses, extra payments, allowances, and benefits in cash or kind (e.g., shares, insurance, social benefits) | `35000.00` |
| `remuneration_currency` | String | No | Currency code (e.g., `EUR`, `USD`, `GBP`, `CHF`) | `EUR` |
| `remuneration_start_date` | Date | No | When this salary period begins | `2024-01-01` |
| `remuneration_end_date` | Date | No | When this salary period ends (empty if ongoing) | `2024-12-31` |
**Remuneration definition**: The remuneration amount should include the employee's **annual gross salary** plus bonuses, extra payments, allowances, and benefits in cash or kind (e.g., shares, insurance, social benefits). This is the total compensation figure used for pay gap analysis.
### Example CSV
```csv theme={"theme":{"light":"github-light","dark":"github-dark"}}
external_employee_id,birth_date,gender,disabled_employee,contract_type,contract_start_date,contract_end_date,contract_end_date_reason,location,employment_category,working_hours_ratio,labor_agreement,remuneration_amount,remuneration_currency,remuneration_start_date,remuneration_end_date
EMP001,1990-05-15,F,no_disability,permanent,2024-01-01,,,,ES,Engineer,1.0,true,35000.00,EUR,2024-01-01,
EMP002,1985-11-20,M,no_disability,permanent,2023-06-01,,,,ES,Manager,1.0,true,48000.00,EUR,2024-01-01,
EMP003,1995-03-10,F,disability_33,temporary,2024-03-01,2024-09-30,,ES,Analyst,0.5,false,18000.00,EUR,2024-03-01,2024-09-30
EMP004,1988-08-25,M,disability_65,permanent,2022-01-01,2024-06-30,resignation,DE,Developer,1.0,true,42000.00,EUR,2024-01-01,2024-06-30
EMP005,1992-12-01,O,with_disability,permanent,2024-07-01,,,,FR,Designer,0.8,true,30000.00,EUR,2024-07-01,
```
## How to upload
Navigate to the **Workforce** section under **Data** in the Dcycle app. You'll see the list of employees (empty if this is your first upload).
Click the **Upload** button in the top right. This opens the data import interface.
You can paste data from a spreadsheet, upload a CSV or Excel file, or enter data manually. The importer maps your columns to the expected fields.
The importer checks your data in real time:
* **Errors** (red): Must be fixed before uploading (e.g., missing required fields, overlapping contracts)
* **Warnings** (yellow): Optional corrections (e.g., unusual values)
Common validation checks:
* No duplicate Employee ID + contract start date combinations
* Contract dates don't overlap for the same employee
* Remuneration dates fall within the parent contract dates
* Gender values are valid (`M`, `F`, `O`, `NS`)
* Working hours ratio is between 0 and 1
Once all errors are resolved, confirm the upload. The file is sent for processing, and you'll see a notification when it completes.
## Viewing contract data
### Employee list
The employee list shows all uploaded employees with key information at a glance:
* **Employee ID**: The external identifier from your HR system
* **Employment category**: Job category/classification
* **Location**: Country where the employee works
* **Contract dates**: Start and end date of the current/latest contract
* **Upload source**: Which file the record came from
You can **search** by Employee ID and **filter** by:
* Upload file (to see records from a specific import)
* Upload date range
### Employee detail
Click on any employee to see their full record:
* **Personal data**: Employee ID, birth date, gender, disability status
* **Contract history**: All contracts with their type, dates, location, category, working hours ratio, and labor agreement status
* **Remuneration history**: Salary periods within each contract, showing amount and currency
* **Trainings**: All training records linked to this employee
* **Absenteeisms & Accidents**: All absence and accident records
## How it appears in reports
Contract and remuneration data feeds into these report sections:
### Headcount and FTE
| Dimension | What it shows |
| ---------------- | ---------------------------------------------------------------------------------- |
| By gender | Number of employees and FTE split by Male, Female, Other |
| By country | Workforce distribution across countries |
| By contract type | Permanent vs Temporary breakdown |
| By workday type | Full-time vs Part-time (based on working hours ratio) |
| By job category | Distribution across employment categories |
| By age group | Grouped by age ranges calculated from birth date |
| By disability | Employees grouped by disability grade (no disability, with disability, ≥33%, ≥65%) |
### Remuneration analysis
| Metric | Description |
| ------------------------ | ------------------------------------------------------------------ |
| Average remuneration | Mean salary by gender, job category, age group |
| Gender pay gap | Percentage difference between male and female average remuneration |
| Remuneration by category | Average salary per employment category |
### Turnover
| Metric | Description |
| ------------- | ------------------------------------------------------ |
| New hires | Employees whose contract started during the period |
| Departures | Employees whose contract ended during the period |
| Turnover rate | Departures / Average headcount |
| End reasons | Breakdown by resignation, termination, contract change |
## Field reference
### Gender values
| Value | Meaning |
| ----- | ------------- |
| `M` | Male |
| `F` | Female |
| `O` | Other |
| `NS` | Not specified |
### Contract types
| Value | Meaning |
| ----------- | ------------------------------------------- |
| `permanent` | Open-ended employment contract |
| `temporary` | Fixed-term contract with a defined end date |
### Contract end reasons
| Value | Meaning |
| -------------------- | ------------------------------------------------------------------------------- |
| `resignation` | Employee voluntarily left |
| `termination` | Employer ended the contract |
| `change_of_contract` | Contract ended because a new contract was issued (e.g., temporary to permanent) |
| `retirement` | Employee retired |
| `fatality` | Contract ended due to the employee's death in service |
All end reasons except `change_of_contract` count as departures for the **turnover** metric (the employee leaves the organization). `change_of_contract` is excluded because the employee stays.
### Working hours ratio
The ratio represents the fraction of a full-time schedule:
| Ratio | Meaning |
| ------ | ------------------------------------ |
| `1.0` | Full-time |
| `0.5` | Half-time |
| `0.8` | 80% of full-time (e.g., 4 days/week) |
| `0.25` | Quarter-time |
**Best practice**: Use your payroll system's FTE values directly. If an employee works 30 hours in a 40-hour-week organization, the ratio is `0.75`.
## Frequently asked questions
No. Each upload is scoped to a single organization. If you have subsidiaries, upload workforce data separately for each one. Reports will consolidate across the organization tree automatically.
If the Employee ID already exists in the organization, the system will add the new contract and remuneration data to the existing employee record. It will not create a duplicate employee.
Upload a new row with the same Employee ID and updated contract details. If the contract dates overlap with an existing contract, the upload will fail -- you'll need to delete the old record first or adjust the dates.
Remuneration fields are optional. You can upload employee and contract data without salary information. However, pay gap metrics will not be available in reports without remuneration data.
Create two rows with the same Employee ID:
1. First row: temporary contract with an end date and reason `change_of_contract`
2. Second row: permanent contract starting after the temporary one ends