Add contracts by employee

This endpoint allows adding contracts with constraints for an employee.

PUT /api/v2/businesses/{businessId}/employees/{employeeId}/contracts

A detailed explanation of each field that can make up the request body is provided below.

Required fields are marked with (*).

Accepted values for Enum type fields are shown in the collapsible details.

Request body

JSON analysis 
{
    "business": "string",
    "ignoreWithoutOuterId": false,
    "ignoreConstraints": false,
    "contracts": [
        {
            "from": "yyyy-MM-dd",
            "to": "yyyy-MM-dd",
            "regularMinutes": 0,
            "weeklyContract": true,
            "dailyContract": true,
            "countingDays": "Enum",
            "additionalMinutes": 0,
            "regularControlPeriod": "Enum",
            "regularPeriodMultiplier": 1,
            "regularPeriodStartDate": "yyyy-MM-dd",
            "additionalControlPeriod": "Enum",
            "additionalPeriodMultiplier": 1,
            "additionalPeriodStartDate": "yyyy-MM-dd",
            "calendarDaysOff": true,
            "numberOfHolidays": 0,
            "numberOfPublicHolidays": 0,
            "holidayEquivalentWorkingMinutes": 0,
            "weeklyDaysInvolved": "Enum",
            "metadata": {},
            "costPerHour": 0,
            "personCategory": "string",
            "id": "string",
            "contractTypeId": "string",
            "completed": true,
            "additionalDailyContract": true,
            "additionalWeeklyContract": true,
            "regularCountingDayType": "string",
            "additionalCountingDayType": "string",
            "constraints": [
                {
                    "id": "constraint.id",
                    "parameters": {
                        "string": 0
                    },
                    "blocks": {
                        "1": {
                            "string": "string"
                        }
                    },
                    "blocking": false
                }
            ]
        }
    ]
}
Details

  • business*: external identifier configured in Orquest for the business.

  • ignoreWithoutOuterId: determines whether entities without a business identifier are taken into account.

  • ignoreConstraints: determines whether the employee’s constraints are updated. If set to true, the constraints in the request will be ignored and only the base contract data will be imported. Existing constraints will not be affected.

  • contracts: list of contracts defined for the employee in the URL. Each contract can have its own constraints.

    • from*: contract start date in yyyy-MM-dd format.

    • to: contract end date in yyyy-MM-dd format. Can be sent as null if no end date has been set.

    • regularMinutes*: regular hours (in minutes) established in the contract. The value is interpreted based on the defined time base: annual, weekly, or daily.

    • weeklyContract*: determines whether the regular contract hours are defined on a weekly basis (true).

    • dailyContract: determines whether the regular contract hours are defined on a daily basis (true). If the contract is neither daily nor weekly, it is assumed to be annual.

    • countingDays: in a daily contract, indicates which days count as worked. Its value can be MONDAY_SUNDAY, MONDAY_SATURDAY, LABOR_DAYS, LABOR_MONDAY_SATURDAY or WEEKENDS_AND_HOLIDAYS.

    • additionalMinutes*: additional hours (in minutes) established in the contract. The value is interpreted based on the defined time base: annual, weekly, or daily.

    • regularControlPeriod*: control period for the regular hours established in the contract. Can be WEEKLY, MONTHLY, YEARLY or PERIODS.

    • regularPeriodMultiplier: multiplier index for regularControlPeriod. For example, setting 2 with a weekly regularControlPeriod would define a biweekly cycle. Default value is 1; accepts null or any integer equal to or greater than 1.

    • regularPeriodStartDate: start date of regularControlPeriod in yyyy-MM-dd format. This date is taken into account when regularPeriodMultiplier is greater than 1; if the multiplier equals 1, the date is ignored.

    • additionalControlPeriod*: control period for additional hours. Can be WEEKLY, MONTHLY, YEARLY or PERIODS.

    • additionalPeriodMultiplier: multiplier index for additionalControlPeriod. For example, setting 2 with a weekly additionalControlPeriod would define a biweekly cycle. Default value is 1; accepts null or any integer equal to or greater than 1.

    • additionalPeriodStartDate: start date of additionalControlPeriod in yyyy-MM-dd format. This date is taken into account when additionalPeriodMultiplier is greater than 1; if the multiplier equals 1, the date is ignored.

    • calendarDaysOff*: determines whether holidays will be processed as calendar days (true) or working days (false).

    • numberOfHolidays*: number of holiday days the employee has in their contract.

    • numberOfPublicHolidays*: number of public holidays the employee has in their contract.

    • holidayEquivalentWorkingMinutes: working time in minutes equivalent to a holiday. If omitted or sent as null, the value stored in the system is kept.

    • weeklyDaysInvolved*: days of the week that will be counted (week type). This field can be defined as MONDAY_SUNDAY, MONDAY_SATURDAY, LABOR_DAYS, LABOR_MONDAY_SATURDAY or WEEKENDS_AND_HOLIDAYS.

    • metadata: any additional data related to the contract. The structure of this metadata must be previously configured by the Orquest team.

    • costPerHour: employee’s cost per hour worked.

    • personCategory*: external identifier of the employee’s category. Can be consulted here.

    • id: external identifier of the contract. Must be unique. Limited to 200 characters.

    • contractTypeId: identifier of the contract type to be applied. If included, the contract’s characteristics will be overridden by those of the contract type (more information here). If not specified, contract type filters may be applied to assign one.

    • completed: determines whether the contract is finalized or not. If true is sent along with the contract end date, it will be considered finalized on that date; if no end date is included, the contract will be considered finalized on the date of the request.

    • additionalDailyContract: determines whether the additional contract hours are defined on a daily basis (true).

    • additionalWeeklyContract: determines whether the additional contract hours are defined on a weekly basis (true). If both additionalWeeklyContract and additionalDailyContract are sent as false, the contract is assumed to be annual.

    • regularCountingDayType: day type set for regular hours in a daily contract. Can be a system day type (ALL, WEEKENDS, MONDAY, TUESDAY, WEDNESDAY, etc.) or one defined at the business level.

    • additionalCountingDayType: day type set for additional hours in a daily contract. Can be a system day type (ALL, WEEKENDS, MONDAY, TUESDAY, WEDNESDAY, etc.) or one defined at the business level.

    • constraints: list of constraints to be applied to this contract. Each constraint in the catalog has its own parameters.

      • id*: internal identifier of the constraint.

      • parameters: object that defines the constraint configuration through key-value pairs. Each constraint uses its own parameters. All values are stored as strings.

      • blocks: optional object that groups the configuration blocks of the constraint, indexed by a numeric identifier. Only present in constraint types that support this structure. The set of keys, their data types, and possible values for each block are defined independently for each constraint type.

      • blocking: indicates whether the constraint is blocking or not. If true is sent, violations will block certain operations.

Request example

Once all fields have been analysed, the following is an example of the request body:

{
    "business": "BUSINESSID",
    "ignoreWithoutOuterId": false,
    "ignoreConstraints": false,
    "contracts": [
        {
            "from": "2026-01-15",
            "to": null,
            "regularMinutes": 360,
            "weeklyContract": false,
            "dailyContract": true,
            "countingDays": "WEEKENDS_AND_HOLIDAYS",
            "additionalMinutes": 120,
            "regularControlPeriod": "MONTHLY",
            "regularPeriodMultiplier": 1,
            "regularPeriodStartDate": "2026-01-15",
            "additionalControlPeriod": "MONTHLY",
            "additionalPeriodMultiplier": 1,
            "additionalPeriodStartDate": "2026-01-15",
            "calendarDaysOff": true,
            "numberOfHolidays": 10,
            "numberOfPublicHolidays": 10,
            "weeklyDaysInvolved": "LABOR_DAYS",
            "costPerHour": 200.34,
            "personCategory": "AV",
            "completed": false,
            "additionalDailyContract": true,
            "additionalWeeklyContract": false,
            "regularCountingDayType": "WEEKENDS",
            "additionalCountingDayType": "WEEKENDS",
            "constraints": [
                {
                    "id": "constraint.sliding_rested_constraint",
                    "parameters": {
                        "assigmentIncidence": "false",
                        "skipHolidayWeekends": "false"
                    },
                    "blocks": {
                        "1": {
                            "weekendRestFull": "SATURDAY_OR_SUNDAY",
                            "uniformDistribution": "UNIFORM",
                            "periodicity": "MONTHLY",
                            "restDayAsWork": "false",
                            "maxOccurrences": "0,1",
                            "interval": "0,1",
                            "mandatory": "true"
                        },
                        "2": {
                            "weekendRestFull": "SATURDAY_XOR_SUNDAY",
                            "uniformDistribution": "UNIFORM",
                            "periodicity": "WEEKLY",
                            "restDayAsWork": "false",
                            "maxOccurrences": "0,1",
                            "interval": "0,1",
                            "mandatory": "false"
                        }
                    },
                    "blocking": false
                },
                {
                    "id": "constraint.max_consecutive_worked_days",
                    "parameters": {
                        "min": 1,
                        "max": 6
                    },
                    "blocking": false
                }
            ]
        }
    ]
}

If all data is correct, a contract will be created for the employee with the characteristics and constraints specified in the request.

Considerations

If contractTypeId is sent, all constraints —including those defined manually— are replaced by those from the contract type.

If contractTypeId is not sent, only constraints whose origin is Importer are replaced by those in the request; constraints defined manually are preserved in the system.

A contract type and constraints cannot be sent in the same request: if both contractTypeId and constraints are sent, the request returns an error.

Error codes

In addition to the common errors, this endpoint can return the following codes:

Code Message Description

400 Bad Request

Constraint '<id>' not found in business catalog

The constraint identifier (id) sent in a contract does not match any constraint in the business catalog. It is recommended to check the constraints catalog.

[…​] cannot specify both contractTypeId and constraints simultaneously.

Both contractTypeId and constraints are sent in the same contract.

Business mismatch: employee belongs to '<business>' but request specifies '<business>'

The business specified in the request does not match the employee’s actual business.

PersonCategory '<id>' not found in business '<business>'

The employee category identifier (personCategory) sent in a contract does not exist in the business. It is recommended to check the available employee categories.

DayType '<id>' not found in business

The day type sent in regularCountingDayType or additionalCountingDayType does not exist at the business level.

ContractType '<id>' not found in business '<business>'

The contract type identifier (contractTypeId) sent does not exist in the business.

Contract '<id>': block orderValue keys […​] must be positive integers

The order keys (orderValue) defined in a constraint’s blocks are not positive integers.

It is recommended to review the response body in case of an error, as it includes relevant information for diagnosis and debugging, such as invalid fields or unrecognized values.

Useful links

What is a contract? And a contract type?

How to apply a contract type?

What is a constraint?

How to query the constraints catalog?