Employee Ingest API Support Guide

This document explains the employee ingest fields from the perspective of a customer-side or third-party integration team. It focuses on what each field means, how it affects codeto plan and codeto report, and which values need particular care when preparing data.

The ingest creates or updates employees and their contracts. Contract-related fields can be time-dependent: when a value changes over time, provide the value with the correct validity period so codeto plan and codeto report can apply it to the right weeks, reports, balances, and planning views.

DTO Overview

The employee ingest accepts one or more employees. Each employee has top-level employee fields and one or more contracts below it. Fields marked as VersionableProperty<T> are arrays of values with validity periods, as described in the next section.

type VersionedValue<T> = {
  value: T;
  validFrom: string;
};

type VersionableProperty<T> = VersionedValue<T>[];

type EmployeeIngestPayload = CreateEmployeeDto[];

type CreateEmployeeDto = {
  employeeId: string;
  contracts: CreateContractDto[];
  firstName: VersionableProperty<string>;
  lastName: VersionableProperty<string>;
  username: VersionableProperty<string>;
  language: VersionableProperty<string>;
};

type CreateContractDto = {
  contractId: string;
  subsidiaryId: string;
  costCenterIds: VersionableProperty<string[]>;
  employmentLevel: VersionableProperty<number>;
  apprenticeshipYear: VersionableProperty<string>;
  salaryType: VersionableProperty<string>;
  roleId: VersionableProperty<string>;
  employeeCategory: VersionableProperty<string>;
  workingPattern: WorkingPattern;
  workingPeriods: WorkingPeriod[];
  salaryComponents: SalaryComponents;
};

type WorkingPattern = {
  monday: VersionableProperty<number>;
  tuesday: VersionableProperty<number>;
  wednesday: VersionableProperty<number>;
  thursday: VersionableProperty<number>;
  friday: VersionableProperty<number>;
  saturday: VersionableProperty<number>;
  sunday: VersionableProperty<number>;
};

type WorkingPeriod = {
  startDate: string;
  endDate: string;
};

type SalaryComponents = {
  controllingCode: VersionableProperty<string>;
  billingRate: VersionableProperty<number>;
  overtimePayCode: VersionableProperty<number>;
  billingRateMileage: VersionableProperty<number>;
  vehicleBillingType: VersionableProperty<number>;
  dailyAllowance: VersionableProperty<number>;
  vacationBalanceLastPayRun: number;
  overtimeBalanceLastPayRun: number;
  gavBalanceLastPayRun: number;
  vacationMonthlyAllowance: number;
};

Versionable Attributes

Some fields are versionable, meaning the value can change over time and codeto plan or codeto report may need to know which value was valid on a specific date. A versionable field should therefore be sent with the correct effective period whenever the source system supports historical or future-dated changes.

Each version is identified by its validFrom date. This date defines the first day on which the value applies. The system computes the validity boundaries automatically from the sequence of validFrom dates: a version is valid from its validFrom up to the day before the next version's validFrom, or indefinitely if no later version exists.

For example, if an employee moves to a different cost center on 2026-04-01, send the old cost center as a version with its original validFrom, and the new cost center as a second version with validFrom: "2026-04-01". The system will treat the old value as valid up to and including 2026-03-31 and the new value as valid from 2026-04-01 onward. This allows older reports, balances, planning entries, and archive documents to keep using the value that was correct at the time.

Date conventions

Versionable property periods are derived from validFrom dates as described above (the previous version's effective period ends the day before the next validFrom). This is not the same convention as workingPeriods, where endDate is inclusive, see the workingPeriods section for that case.

Employee Fields

employeeId

Unique identifier of the employee in the source system.

Use a stable value that does not change over the employee's lifecycle. codeto plan and codeto report use this identifier to recognize the same employee in later ingests.

The value must be globally unique across the entire customer environment.

Examples:

• Use the HR master-data employee number if it remains stable after name, department, or contract changes.
• Email addresses are usually less suitable when they can change after marriage, rebranding, or account migrations.

firstName

Employee's legal or source-system first name.

This name is used for display, search, and employee identification. In codeto plan, users may maintain a separate display name that can be shown instead in some views. In codeto report, the ingested first name remains the relevant source value for employee display and reporting.

firstName is versionable: send each historical name as a separate version with the date it became effective if the source system tracks name changes over time. A single version with the current name is sufficient if no history is available.

Examples:

• If the source system changes firstName from Jon to Jonathan on 2026-03-01, send the old value with its original validFrom and a second version with value: "Jonathan" and validFrom: "2026-03-01".
• If codeto plan users maintain a display name such as John, that display name may appear in planning views even though codeto report still uses the ingested first name.

lastName

Employee's legal or source-system last name.

This name is used together with the first name for display, search, report views, and archived documents. As with firstName, codeto plan may support a separate display name, while codeto report primarily relies on the ingested value.

lastName is versionable in the same way as firstName: send each historical last name as its own version with the appropriate validFrom if the source system tracks name changes (e.g. after marriage).

Examples:

• If an employee's last name changes, update this field so future report views and archive documents use the new name.
• Keep historic employee identifiers stable when changing the name; do not create a new employee just because the last name changed.

username

Login or account name of the employee, if available.

This field is stored for identification and possible downstream use. It does not currently drive planning, reporting, balance, or approval behavior.

username is versionable: send each historical login as its own version with the date it became effective if the source system tracks login changes. A single version with the current value is sufficient otherwise.

language

Preferred employee language.

This affects employee-facing communication such as notifications. In codeto report it also affects the language used for employee archive documents. Provide a value that matches the language the employee should receive official or operational communication in.

Accepted values are de (German), fr (French), it (Italian), and en (English), following the ISO 639 lowercase convention.

Examples:

• Use de for an employee who should receive German notifications and German codeto report archive documents.
• Use fr for an employee working in a French-speaking subsidiary if their official communication should be in French.

contracts

List of contracts belonging to the employee.

An employee needs at least one valid contract to appear in codeto plan and codeto report. Contracts define where the employee belongs organizationally, when the employee is active, how working time is calculated, which reporting rules apply, and which balances are shown.

Examples:

• An employee with one ongoing contract usually has one contract entry with an active working period.
• An employee who moved from one subsidiary to another may have two contracts, each with its own subsidiary and working period.
• An employee who left and later rejoined can have separate working periods or contracts, depending on how the customer's HR system models the rehiring.

Contract Fields

contractId

Unique identifier of the contract.

Use a stable value that remains the same across ingests for the same contract. codeto plan and codeto report use the contract identifier to attach planning entries, bookings, reports, balances, approvals, and archive documents to the correct contract. Changing it disconnects new data from previously created planning or reporting history.

The value must be globally unique across the entire customer environment, not only unique per employee.

Examples:

• Use the HR contract number if it is unique and remains stable across payroll and organizational changes.
• Do not reuse the same contractId for a renewed contract if the old and new contracts must keep separate reporting or balance history.

subsidiaryId

Identifier of the subsidiary or company unit the contract belongs to.

This is one of the most important scoping fields. It determines which company configuration applies to the contract, including working-time rules, holiday calendars, report settings, rounding behavior, and authorization boundaries.

In codeto plan, the subsidiary influences who can see or edit the employee and which organizational working-time context is used. In codeto report, it affects when the employee appears in reporting, which rules are applied to reports, and which company information appears on archive documents.

Examples:

• If an employee moves from subsidiary CH01 to CH02, this requires a new contract referencing CH02. subsidiaryId is not versionable, so a subsidiary change cannot be expressed as a new version on the existing contract.
• If subsidiary-based permissions are used, the assigned subsidiary is part of the access-control context.

costCenterIds

Cost centers assigned to the contract.

Use this field to attribute the employee or contract to one or more cost centers. These values are used for filtering, cost-center-specific views, report summaries, exports, and archive documents.

Examples:

• Assign one cost center when the employee's work belongs to a single accounting unit.
• Assign multiple cost centers if the customer's reporting setup expects the contract to be visible under more than one cost-center filter.
• Update the value when the employee moves to a different accounting unit so future reports and exports use the correct attribution.

employmentLevel

Employment percentage for the contract, usually from 0 to 100.

This is shown as contract metadata and can be used for filtering or grouping employees. It represents the agreed employment level. For working-time and reporting calculations, provide the actual expected hours per weekday in workingPattern. The provided working pattern is not normalized using the employment level.

Examples:

• A full-time employee is typically sent as 100.
• A 60% employee is typically sent as 60, while workingPattern should still contain the actual expected hours for each weekday.

apprenticeshipYear

Apprenticeship year for the employee, if relevant.

This field is stored as contract metadata. It does not currently change codeto plan or codeto report behavior, but it can be useful for display, exports, or future integration needs.

salaryType

Salary category of the contract.

Accepted values are S for hourly-paid employees and M for monthly-paid employees.

The field distinguishes hourly-paid and monthly-paid employees. This matters primarily in codeto report:

• hourly-paid employees can be handled differently for public holidays, balances, and absence validation;
• monthly-paid employees are generally expected to follow the configured target hours and reporting rules.

codeto plan scheduling behavior is not currently changed by this field.

Examples:

• Use S for employees whose public holidays and balances should follow hourly-paid rules.
• Use M for employees whose reports should be checked against regular target hours.

roleId

Role assigned to the contract.

In codeto plan, the role helps classify employees in planning views and can affect which employees appear in role-based selections. In codeto report, the role is shown as contract information on report-related views and documents.

This field does not by itself define report approval routing. Approval behavior depends on the customer's configured reporting and project responsibilities.

Examples:

• Assign a role such as project manager or site manager if codeto plan should include the employee in role-based planning selections.
• Update the role from the effective date when an employee changes function, so planning and report displays show the correct current role.

employeeCategory

Customer-specific employee category.

This field is stored as contract metadata. It does not currently change codeto plan or codeto report behavior directly, but it may be useful for exports, classification, or future filtering.

workingPattern.monday through workingPattern.sunday

Expected working hours for each weekday.

This is the central field group for target-hour calculations. Provide the actual expected working time for each weekday for this contract, i.e. the agreed schedule as it should appear day by day. Do not scale these values by employmentLevel; they are used as given and are not normalized. For example, if a part-time employee works four hours on Mondays, the Monday value should be four hours, not the full-time company default.

In codeto plan, the working pattern influences utilization and policy-related calculations. It may not visually change every planning calendar view, because some calendar displays are based on subsidiary-level working-time settings.

In codeto report, the working pattern determines expected hours, report summaries, approval warnings, overtime or GAV-related checks, archive document totals, and whether days are considered working days.

Examples:

• A full-time weekday pattern could be Monday to Friday 8, Saturday 0, Sunday 0.
• A 60% employee working Monday, Tuesday, and Thursday could be sent as 8, 8, 0, 8, 0, 0, 0.
• An employee who never works on Wednesdays can have Wednesday set to 0.

workingPeriods

Date ranges during which the contract is active.

Each working period has a startDate and an inclusive endDate. The periods define when the employee can be planned, when reports are expected, and which contract applies for a given date.

In codeto plan, working periods define the date ranges in which the employee is available on the planning timeline and can receive bookings.

In codeto report, working periods determine whether reports are created or shown for a week, which contract receives the report, which subsidiary configuration applies, and which company information appears in archive documents.

Use separate periods when the employee should be inactive between two active contract phases.

Examples:

• An ongoing contract can have a startDate and no meaningful end beyond the active employment period, depending on the ingest format agreed with the customer.
• A contract active from 2026-01-01 to 2026-06-30 should only make the employee plannable and reportable inside that range.
• If employment pauses for an unpaid leave, use separate periods only if the employee should not be planned or expected to report during the gap.

Salary Component Fields

salaryComponents.controllingCode

Controlling or accounting code for the contract.

This field is stored for downstream financial, accounting, export, or integration use. It does not currently change codeto plan or codeto report behavior. It can influence egress payloads that include financial attribution or controlling information.

Examples:

• Use the controlling code expected by the customer's payroll, ERP, or finance export.
• Update the value when finance attribution changes and future exports should use the new code.

salaryComponents.billingRate

Billing rate associated with the contract.

This field is stored for downstream billing, accounting, export, or integration use. It does not currently change codeto plan or codeto report behavior. It can influence egress payloads that include billing or rate information.

Examples:

• Provide the hourly or contractual rate that downstream billing exports should receive.
• Update the value from the effective date of a rate change.

salaryComponents.overtimePayCode

Code that indicates whether overtime handling is enabled for the contract. Numeric values below 5 enable overtime handling; values of 5 or greater disable it.

codeto report uses this information to decide whether overtime-related automatic additions, warnings, or balance behavior should apply. A value that disables overtime can move the employee into a different reporting mode where deviations from target hours are handled differently.

codeto plan scheduling behavior is not currently changed by this field.

Examples:

• Use a value below 5 for employees whose additional eligible work should contribute to overtime handling in codeto report.
• Use a value of 5 or greater for employees whose target-hour deviations should be treated under the customer's non-overtime or profit-sharing rules.

salaryComponents.billingRateMileage

Mileage billing rate associated with the contract.

This field is stored for downstream billing, accounting, export, or integration use. It does not currently change codeto plan or codeto report behavior. It can influence egress payloads that include mileage billing or reimbursement information.

Examples:

• Provide the mileage rate expected by the customer's billing or reimbursement export.
• Update the value when the reimbursed mileage rate changes.

salaryComponents.vehicleBillingType

Vehicle billing category. Accepted numeric values are:

• 0: no vehicle billing
• 1: private vehicle billing
• 2: company vehicle billing

The field is stored for downstream billing, accounting, export, or integration use. It does not currently change codeto plan or codeto report behavior.

Examples:

• Use 1 when mileage should be associated with a private vehicle.
• Use 2 when mileage should be associated with a company-provided vehicle.
• Use 0 when no vehicle billing should apply.

salaryComponents.dailyAllowance

Indicator for whether daily allowance rules apply to the contract.

codeto report uses this value when deciding whether daily-allowance-dependent additions should be generated for this contract.

codeto plan scheduling behavior is not currently changed by this field.

Examples:

• Enable this field for employees who should receive daily-allowance-dependent additions when their reports meet the configured conditions.
• Disable it for employees who should never receive those additions, even if other reported work conditions match.

salaryComponents.vacationBalanceLastPayRun

Vacation balance carried over from the last payroll run, expressed in hours.

This is the starting point for codeto report vacation balance calculations. codeto report adds later vacation usage, corrections, and entitlements on top of this base value.

codeto plan does not currently display or calculate vacation balances.

Examples:

• If payroll closed with 42 vacation hours remaining, send 42 as the carry-over so codeto report starts from that balance.
• If a correction was already applied in payroll before the cutover, send the corrected remaining balance rather than the pre-correction value.

salaryComponents.overtimeBalanceLastPayRun

Overtime balance carried over from the last payroll run, expressed in hours.

This is the starting point for codeto report overtime balance calculations. Later reported work, compensation, and adjustments are calculated relative to this base value.

codeto plan does not currently display or calculate overtime balances.

Examples:

• If payroll closed with 10.5 overtime hours, send 10.5 as the starting overtime balance.
• If the employee had compensated all overtime before the cutover, send 0.

salaryComponents.gavBalanceLastPayRun

GAV balance carried over from the last payroll run, expressed in hours.

This is the starting point for codeto report GAV balance calculations where GAV tracking applies. Later relevant events and adjustments are calculated relative to this base value.

codeto plan does not currently display or calculate GAV balances.

Examples:

• Send the GAV balance from the last payroll run when the employee is subject to GAV tracking.
• Send 0 if payroll has no remaining GAV balance at the cutover point.

salaryComponents.vacationMonthlyAllowance

Monthly vacation entitlement, expressed in hours.

codeto report uses this value to calculate vacation entitlement over time, including pro-rata projections for the rest of the year based on the employee's active working periods. Incorrect values affect vacation balances, projected vacation entitlement, balance summaries, and vacation details shown in codeto report.

codeto plan does not currently display or calculate vacation entitlements.

Examples:

• If the employee earns 14 vacation hours per month, send 14.
• For a part-time employee, send the already pro-rated monthly entitlement if the customer's payroll system calculates entitlement that way.