Own Workforce Import Templates - Dcycle Platform Docs

← Imports To send own workforce data from your systems, POST /v2/own-workforce/employees creates employees with their contracts and remunerations, and trainings and absences have their own v2 routes (POST /v2/own-workforce/trainings, POST /v2/own-workforce/absences). To load a file, the Imports API exposes these templates:

`template_id`	What a row creates
`own_workforce`	An employee, their contract, and optionally a remuneration period
`own_workforce_contracts`	Employee contract fields; custom columns belong to the contract
`own_workforce_remunerations`	Employee and contract context plus remuneration fields; custom columns belong to the remuneration
`own_workforce_trainings`	A training record for an existing employee
`own_workforce_accidents_absenteeisms`	An accident, an absence, or an accident plus the absence it caused

There is no endpoint that lists the available template_id values. Get Template fetches one by id, but there is no catalogue to enumerate them. These ids are only discoverable from this page, so treat them as the reference.

Use them through the normal flow: create a session with the template_id and your file, map the columns, validate, correct rows if needed, then submit. Submission is asynchronous — poll the status.

Order matters

own_workforce_trainings and own_workforce_accidents_absenteeisms attach rows to an employee by external_employee_id, and the accepted values are the employees that already exist in the organization. Import own_workforce first; the other two will reject rows for people the system does not know yet.

A note on “required”

In the Get Template response, required: true appears only for columns with a hard required rule. Columns that are conditionally required — through required_with or required_without — come back as required: false, with the condition inside validations. Reading only the boolean will tell you a column is optional when in practice it is mandatory as soon as you fill in its siblings. The tables below mark those as conditional.

`own_workforce` — employees, contracts and pay

Each row creates or updates one employee and their contract, plus a remuneration period when the pay columns are filled in.

Column	Type	Required	Notes
`external_employee_id`	string	yes	Your HR identifier. Unique per organization, so the same value may exist in a sibling organization.
`organization_id`	category	yes	Which organization of your tree the row belongs to
`disabled`	category	yes	`no_disability`, `with_disability`, `disability_33`, `disability_65`
`gender`	category	yes	`M`, `F`, `O`, `NS`. Common aliases in several languages are accepted.
`birth_date`	date	yes	Not in the future, year 1900 or later
`location`	category	yes	Country of work
`nationality`	category	no	Left blank, the employee’s nationality stays empty
`contract_type`	category	yes	From the contract-type catalogue
`contract_start_date`	date	yes	Year 1900 or later. A contract the employee already has with this start date is updated. A new one closes the stored open contract before it the day before it starts, and must start after the end date another row sends for the stored contract before it. If no stored contract is before it but one is after, an open new one ends the day before that one starts. Contracts added by the same block of rows are not closed for each other: fill in the end date of every one but the employee’s last.
`contract_end_date`	date	no	Must not precede `contract_start_date`. Blank means open-ended, or keeps a stored contract’s end date. For a stored contract (same start date), another end date ends the contract and its remunerations that run past it on that day. It must be before the employee’s next contract starts.
`contract_end_date_reason`	category	no	From the end-reason catalogue. Needs an end date: the row’s, the stored one, or one another contract gives it as `contract_start_date` describes; for a stored contract, another row’s end date for it counts too. A new contract without one fails its row; for a stored open contract the row is imported without the reason and says so. A stored open contract can be sent again with the reason it has. Blank keeps a stored contract’s reason.
`working_hours_ratio`	float	yes	Greater than 0, up to 1. This is what drives FTE.
`labor_agreement`	category	yes	Boolean, with multilingual aliases
`employment_category`	string	yes	Free text — the job category
`contract_annual_working_hours`	float	no	Greater than 0, up to 2928 (8 h × 366 d)
`remuneration_start_date`	date	conditional	Required once any other remuneration column is filled. Must not precede `contract_start_date`. Identifies the remuneration in its contract: a stored one with this start date takes the row’s amount and keeps its dates; a new one closes the stored open remuneration before it the day before it starts. To record a new year’s salary as its own period, start it on the year’s first day (or the hire date within the year).
`remuneration_end_date`	date	no	Must not precede `remuneration_start_date`
`remuneration_amount`	float	conditional	Required with the other remuneration columns. Zero or greater.
`remuneration_currency`	category	conditional	Required with the other remuneration columns

Remuneration start, amount and currency are required together; the end date stays optional. Leave all remuneration columns blank to import an employee and contract with no pay data. Send the same contract fields in every row of a contract, and keep each employee’s rows next to each other: a large file is applied in blocks of 15,000 rows, and a row’s contract rules (its end date, its end reason, a new contract closing the previous one) take into account the rows of its block, with the rows of earlier blocks already stored.

Scoped contract and remuneration imports

own_workforce_contracts and own_workforce_remunerations reuse the native columns and validation rules above. The app fixes the employee context when the import is opened from its child list, and fixes the selected contract for remuneration imports. The remuneration template always requires remuneration_start_date, remuneration_amount and remuneration_currency. These two template ids and own_workforce_accidents_absenteeisms offer the destination’s importable custom columns and allow declaring columns from file headers. A contract template writes only the contract sidecar, a remuneration template only the remuneration sidecar, and an accident/absence template the combined parent record. Required fields, defaults, types and relation resolution use the standard custom-column import rules. Formula and user fields follow the same import restrictions as other categories. Native records are retained if a custom-value write fails; the processing job reports missing custom values in its error summary. Deploy the updated worker before enabling the manual-entry feature for clients. The scoped templates use the existing Own Workforce heavy-file category; no new worker queue category is introduced.

`own_workforce_trainings` — training records

Column	Type	Required	Notes
`description`	string	yes	What the training was
`external_employee_id`	category	yes	Must match an employee already in the organization
`organization_id`	category	no	Multi-organization files only. Blank, or absent entirely, falls back to the organization of the upload — so single-organization imports are unaffected.
`type`	string	yes	Free text
`start_date`	date	yes	Year 1970 or later
`end_date`	date	yes	Must not precede `start_date`
`hours`	float	yes	Zero or greater

`own_workforce_accidents_absenteeisms` — absences and accidents

One row can carry an accident, an absence, or both. The shape is driven by which columns you fill.

Column	Type	Required	Notes
`external_employee_id`	category	yes	Must match an employee already in the organization
`organization_id`	category	no	As above — blank falls back to the upload’s organization
`absenteeism_accident_type`	string	yes	Free text label
`absenteeism_accident_context`	category	conditional	`in_labore` or `in_itinere`. Required when `accident_date` is set.
`accident_date`	date	conditional	Required when a context is given. Cannot be in the future.
`absenteeism_start_date`	date	conditional	Required when the other absence columns are filled, and required when there is no `accident_date`. Must not precede `accident_date`.
`absenteeism_end_date`	date	no	Must not precede `absenteeism_start_date`
`absenteeism_total_hours`	float	no	Greater than 0

In practice: a row with only accident columns records an accident; a row with only absence columns records an absence; a row with both records an accident and the sick leave it caused, linked together.

Validation rules

Five rules apply per row and two across the whole file. Two of the seven are warnings, which annotate a row without blocking the import.

Per row

Rule	Severity	What it checks
`own_workforce_employee_belongs_to_org`	error	The employee exists in the organization the row resolves to
`own_workforce_accident_not_duplicate`	error	No accident is already recorded for that employee on that date
`own_workforce_absenteeism_not_overlapping`	error	The absence does not overlap one already stored for that employee
`own_workforce_accident_within_contract`	warning	The accident date falls inside one of the employee’s contracts
`own_workforce_absenteeism_within_contract`	warning	The absence falls inside one of the employee’s contracts

Across the file

Rule	Severity	What it checks
`own_workforce_duplicate_accident_in_file`	error	No two rows give the same employee an accident on the same date
`own_workforce_absenteeism_overlap_in_file`	error	No two rows give the same employee overlapping absences

Both file-level rules flag every row in the offending group, not just the second one, so a duplicate shows up twice in the error list.

The employee is resolved against the row’s effective organization — the organization_id cell when filled, otherwise the organization of the upload. This matters in a group: the same external_employee_id can legitimately exist in several organizations of the tree, and the rule checks the one the row points at.

Category values

Columns typed category accept a fixed set of values, which you can fetch at runtime with Get Options Source. location, nationality and organization_id resolve against the shared country and organization sources; the workforce-specific ones are:

Source key	Values
`own_workforce_genders`	`M`, `F`, `O`, `NS`, plus multilingual aliases
`own_workforce_disability_grades`	`no_disability`, `with_disability`, `disability_33`, `disability_65`
`own_workforce_accident_contexts`	`in_labore`, `in_itinere`
`own_workforce_boolean`	true/false, with multilingual aliases
`own_workforce_contract_types`	The contract-type catalogue
`own_workforce_contract_end_reasons`	The end-reason catalogue
`own_workforce_external_employee_ids`	The employees that already exist in your organization

Only the last one is organization-specific: it is resolved live against your employees, so fetch it per organization rather than caching it. The contract-type and end-reason catalogues are shared across organizations.

Create an import session

Start here, with one of the three template_id values

Get template

Fetch a template’s columns at runtime

Validate

Apply the rules above before submitting

Own Workforce API

Read back what you imported

​Order matters

​A note on “required”

​own_workforce — employees, contracts and pay

​Scoped contract and remuneration imports

​own_workforce_trainings — training records

​own_workforce_accidents_absenteeisms — absences and accidents

​Validation rules

​Per row

​Across the file

​Category values

​Related Endpoints

Create an import session

Get template

Validate

Own Workforce API

Order matters

A note on “required”

`own_workforce` — employees, contracts and pay

Scoped contract and remuneration imports

`own_workforce_trainings` — training records

`own_workforce_accidents_absenteeisms` — absences and accidents

Validation rules

Per row

Across the file

Category values

Related Endpoints