Add contracts with constraints

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,
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.

 
"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,
        "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,
                    "string": 0
                },
                "blocking": false
            }
        ]
    }
]
Details

  • 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 or YEARLY.

  • 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 or YEARLY.

  • 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.

  • 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.

    • blocking. Indicates whether the constraint is blocking or not. If true is sent, violations will block certain operations. This field is currently ignored and all constraints are created with false as the default value.

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.presence_total_minutes",
                    "parameters": {
                        "max": 360
                    },
                    "blocking": false
                },
                {
                    "id": "constraint.weekly_rotative_rest",
                    "parameters": {
                        "mandatory": true,
                        "rest": 4.0,
                        "rotation": 4.0
                    },
                    "blocking": false
                }
            ]
        }
    ]
}

If all data is correct, a contract will be created for the employee with the characteristics and constraints specified in the request (Maximum shift duration and Free days rotation).

Considerations

If the employee specified in the URL does not exist, the request will return a 404 Not Found error indicating Person does not exist.

If the constraint identifier (id) does not match any constraint in the business catalog, the request will return a 400 Bad Request error indicating Constraint not found in business catalog.

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 will return a 400 Bad Request error indicating […​] cannot specify both contractTypeId and constraints simultaneously.

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?