v1

latestOpenAPI 3.1.02026-07-26549156879.0 KB

Contracts > ContractVersion

Creates a Contract version

post/api/2026-07-01/resources/contracts/contract_versions

Request body

employee_idstring required

employee identifier, refers to /employees/employees endpoint.

effective_onstring required

the day the specific contract starts, in case of hiring the same than starts_on.

starts_onstring required

the day the employee is hired.

ends_onstring

the day the employee is terminated.

working_hours_frequencystring

the frequency of the working hours.

working_week_daysstring

the days of the week the employee works.

working_hoursinteger

the amount of hours the employee works.

max_legal_yearly_hoursinteger

the maximum amount of hours the employee can work in a year.

maximum_weekly_hoursinteger

the maximum amount of hours the employee can work in a week.

min_rest_minutes_between_daysinteger

the minimum amount of minutes the employee must rest between working periods.

max_work_minutes_per_dayinteger

the maximum amount of minutes the employee can work in a day.

max_work_days_in_rowinteger

the maximum amount of days the employee can work in a row.

min_rest_hours_in_rowinteger

the minimum amount of hours the employee must rest in a row.

salary_frequencystring

the frequency of the salary payment. When adding a salary to a contract that previously had none, both salary_amount and salary_frequency must be provided together.

salary_amountinteger

the amount of money the employee earns in cents.

job_titlestring

job title of the employee.

has_trial_periodboolean

a flag that indicates if the employee has a trial period.

trial_period_ends_onstring

when the trial period ends.

working_time_percentage_in_centsinteger

Working time percentage in cents (e.g., when an employee is working part-time, the percentage of full-time hours they are working).

annual_working_time_distribution'limit_workdays' | 'limit_daily_hours'

Allows companies to define how annual working hours are spread across the year to ensure compliance with legal limits.

copy_current_contract_versionboolean

wether to copy the current contract version.

bank_holiday_treatment'workable' | 'non_workable'

Defines whether a bank holiday should be considered as a workable or non-workable day.

job_catalog_tree_node_uuidstring

the uuid node in the job catalog tree. For now it only supports level nodes. From this point in the job catalog tree you can get the full ancestor path to the root node including the role. Refer to job_catalog/tree_nodes endpoint.

de_base_salary_type_idstring

Identifier for the German base salary type. References a payroll concept available via the /payroll/concepts endpoint.

Example request

{
  "employee_id": "1",
  "effective_on": "2024-10-06",
  "starts_on": "2024-10-06",
  "ends_on": "2024-10-06",
  "working_hours_frequency": "week",
  "working_week_days": "monday,tuesday,wednesday,thursday,friday",
  "working_hours": 40,
  "max_legal_yearly_hours": 2000,
  "maximum_weekly_hours": 40,
  "min_rest_minutes_between_days": 2880,
  "max_work_minutes_per_day": 480,
  "max_work_days_in_row": 6,
  "min_rest_hours_in_row": 36,
  "salary_frequency": "yearly",
  "salary_amount": 1000,
  "job_title": "Designer",
  "trial_period_ends_on": "2024-10-06",
  "working_time_percentage_in_cents": 8000,
  "annual_working_time_distribution": "limit_workdays",
  "copy_current_contract_version": true,
  "bank_holiday_treatment": "workable",
  "job_catalog_tree_node_uuid": "jobcatalog_treelevel-14",
  "de_base_salary_type_id": "1"
}

Response

CREATED

idstring

identifier for the contract version.

company_idstring required

identifier for company.

employee_idstring required

employee identifier, refers to /employees/employees endpoint.

effective_onstring required

the day the specific contract starts, in case of hiring the same than starts_on.

countrystring

nationality country code of the employee (Spain ES, United Kingdom GB).

job_titlestring

job title of the employee.

job_catalog_level_idstring

job catalog level identifier, refers to /job_catalog/levels endpoint.

job_catalog_tree_node_uuidstring

starts_onstring

the day the employee is hired.

ends_onstring

the day the employee is terminated. It has nothing to do with trial period, these are concepts totally unrelated.

has_payrollboolean required

boolean that indicates if the employee asociated to this contract belongs to a payroll policy.

has_trial_periodboolean

a flag that indicates if the contract version has ever had a trial period.

trial_period_ends_onstring

when the trial period ends. If there is no date, it means that the employee has never been in trial. This date is not related with the end date of a contract.

salary_amountinteger

the amount of money the employee earns in cents.

salary_frequencystring

the frequency of the salary payment.

working_week_daysstring

the days of the week the employee works.

working_hoursinteger

the amount of hours the employee works.

working_hours_frequencystring

the frequency of the working hours.

max_legal_yearly_hoursinteger

the maximum amount of hours the employee can work in a year.

maximum_weekly_hoursinteger

the maximum amount of hours the employee can work in a week.

bank_holiday_treatment'workable' | 'non_workable' required

Defines whether a bank holiday should be considered as a workable or non-workable day.

working_time_percentage_in_centsinteger

Working time percentage in cents (e.g., when an employee is working part-time, the percentage of full-time hours they are working).

annual_working_time_distribution'limit_workdays' | 'limit_daily_hours'

Allows companies to define how annual working hours are spread across the year to ensure compliance with legal limits.

version_dataobject

Country-specific contract data (template fragments and fields).

min_rest_minutes_between_daysinteger

the minimum amount of minutes the employee must rest between working periods.

max_work_minutes_per_dayinteger

the maximum amount of minutes the employee can work in a day.

max_work_days_in_rowinteger

the maximum amount of days the employee can work in a row.

min_rest_hours_in_rowinteger

the minimum amount of hours the employee must rest in a row.

created_atstring required

the date the contract version was created.

updated_atstring required

the date of the last contract version updated.

es_has_teleworking_contractboolean

flag that indicates if the contract has teleworking.

es_cotization_groupinteger

the group of cotization of the employee.

contracts_es_tariff_group_idstring

the group of cotization of the employee.

es_contract_observationsstring

observations of the contract.

es_job_descriptionstring

the job description of the employee.

es_contract_type_idstring

contract type identifier.

es_working_day_type_idstring

working day type identifier.

es_education_level_idstring

education level identifier.

es_professional_category_idstring

professional category identifier.

fr_employee_typestring

employee type.

fr_forfait_joursboolean required

flag that indicates if the employee is allowed to work within the framework of a fixed number of days.

fr_jours_par_aninteger

the number of days the employee is allowed to work.

fr_coefficientstring

coefficient for france contracts.

fr_contract_type_idstring

contract type identifier.

fr_level_idstring

level identifier.

fr_step_idstring

step identifier.

fr_mutual_idstring

mutual identifier.

fr_professional_category_idstring

professional category identifier.

fr_work_type_idstring

work type identifier.

de_contract_type_idstring

contract type identifier.

de_base_salary_type_idstring

Identifier for the German base salary type. References a payroll concept available via the /payroll/concepts endpoint.

pt_contract_type_idstring

contract type identifier.

Example response

{
  "id": "1",
  "company_id": "1",
  "employee_id": "1",
  "effective_on": "2024-10-06",
  "country": "es",
  "job_title": "Designer",
  "job_catalog_level_id": "1",
  "job_catalog_tree_node_uuid": "jobcatalog_treelevel-14",
  "starts_on": "2024-10-06",
  "ends_on": "2024-10-06",
  "trial_period_ends_on": "2024-10-06",
  "salary_amount": 1000,
  "salary_frequency": "yearly",
  "working_week_days": "monday,tuesday,wednesday,thursday,friday",
  "working_hours": 40,
  "working_hours_frequency": "week",
  "max_legal_yearly_hours": 2000,
  "maximum_weekly_hours": 40,
  "bank_holiday_treatment": "workable",
  "working_time_percentage_in_cents": 8000,
  "annual_working_time_distribution": "limit_workdays",
  "version_data": {
    "country_data": {
      "country": "es",
      "fields": [
        {
          "name": "contract_type",
          "field_name": "Tipo de contrato",
          "value_label": "Indefinido",
          "value_id": "1"
        },
        {
          "name": "working_hours",
          "field_name": "working_hours",
          "value_label": "40",
          "value_id": "40"
        }
      ]
    }
  },
  "min_rest_minutes_between_days": 2880,
  "max_work_minutes_per_day": 480,
  "max_work_days_in_row": 6,
  "min_rest_hours_in_row": 36,
  "created_at": "2024-10-06T00:00:00.000Z",
  "updated_at": "2024-10-06T00:00:00.000Z",
  "es_cotization_group": 1,
  "contracts_es_tariff_group_id": "1",
  "es_contract_observations": "review contract for job promotion",
  "es_job_description": "Designer",
  "es_contract_type_id": "1",
  "es_working_day_type_id": "1",
  "es_education_level_id": "1",
  "es_professional_category_id": "1",
  "fr_employee_type": "apprenti",
  "fr_jours_par_an": 200,
  "fr_coefficient": "1",
  "fr_contract_type_id": "1",
  "fr_level_id": "1",
  "fr_step_id": "1",
  "fr_mutual_id": "1",
  "fr_professional_category_id": "1",
  "fr_work_type_id": "1",
  "de_contract_type_id": "1",
  "de_base_salary_type_id": "1",
  "pt_contract_type_id": "1"
}