Add an employee’s contracts with constraints

This endpoint allows adding contracts with constraints for an employee, supporting the nature (nature) of each constraint.

PUT /api/v2/businesses/{businessId}/people/{employeeId}/contracts-with-constraints

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,
    "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",
            "completed": true,
            "additionalDailyContract": true,
            "additionalWeeklyContract": true,
            "regularCountingDayType": "string",
            "additionalCountingDayType": "string",
            "constraints": [
                {
                    "id": "constraint.id",
                    "parameters": {
                        "string": 0
                    },
                    "blocks": {
                        "1": {
                            "string": "string"
                        }
                    },
                    "blocking": false,
                    "nature": "Enum"
                }
            ]
        }
    ]
}
Details

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

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

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

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

  • 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. Default value is false.

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

      • nature: nature of the constraint. Can be PERSONAL or CONTRACT_TYPE. If not informed, its default value is CONTRACT_TYPE.

Request example

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

{
    "business": "CST",
    "ignoreWithoutOuterId": false,
    "contracts": [
        {
            "from": "2026-06-16",
            "regularMinutes": 380,
            "weeklyContract": false,
            "dailyContract": true,
            "countingDays": "WEEKENDS_AND_HOLIDAYS",
            "additionalMinutes": 150,
            "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",
            "constraints": [
                {
                    "id": "constraint.shift_duration_alternatives",
                    "parameters": {},
                    "blocks": {
                        "1": {
                            "shiftDuration": 630
                        },
                        "2": {
                            "shiftDuration": 1230
                        }
                    },
                    "blocking": false,
                    "nature": "PERSONAL"
                },
                {
                    "id": "constraint.presence_min_total_minutes",
                    "parameters": {
                        "min": "240"
                    },
                    "blocking": false
                }
            ]
        }
    ]
}

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

Considerations

This endpoint supports the nature field on each constraint, allowing you to explicitly indicate whether it was entered manually (PERSONAL) or comes from a contract type or an import (CONTRACT_TYPE).

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.

Contract '<id>': constraints are required

The constraints field was not included in a contract, or was sent empty.

Constraint '<id>': invalid nature '<nature>'. Allowed values are PERSONAL and CONTRACT_TYPE

The value of a constraint’s nature field is neither PERSONAL nor CONTRACT_TYPE.

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.

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 check the response body in case of error, as it includes relevant information for diagnosis and debugging, such as the invalid field or the unrecognized value.

Useful links

What is a contract? And a contract type?

What is a constraint?

How to query the constraints catalog?