Get an employee’s contracts with constraints

This endpoint allows querying an employee’s contracts within a date range, including the constraints applied to each contract.

GET /api/v2/businesses/{businessId}/people/{personId}/contracts-with-constraints?from={yyyy-MM-dd}&to={yyyy-MM-dd}

If the data included in the request is correct —businessId, personId, from and to—, the response will contain the list of the employee’s contracts that overlap with the indicated date range, together with the constraints specific to each contract.

Response example

[
    {
        "from": "2026-01-15",
        "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",
        "employeeId": "XXXX01",
        "completed": false,
        "constraints": [
            {
                "id": "constraint.shift_alternatives",
                "parameters": {},
                "blocks": {
                    "1": {
                        "timeSlots": "10:00,20:00",
                        "weekDays": 2
                    },
                    "2": {
                        "timeSlots": "09:00,10:00",
                        "weekDays": 4
                    }
                },
                "blocking": false,
                "from": "2026-01-15",
                "canceled": false,
                "constraintGroup": "Contract",
                "nature": "PERSONAL"
            },
            {
                "id": "constraint.weekly_rotative_rest",
                "parameters": {
                    "rotation": 4.0,
                    "rest": 4.0,
                    "mandatory": "true"
                },
                "blocking": false,
                "from": "2026-01-15",
                "canceled": false,
                "constraintGroup": "Contract",
                "nature": "CONTRACT_TYPE"
            },
            {
                "id": "constraint.presence_total_minutes",
                "parameters": {
                    "max": 360,
                    "min": 240
                },
                "blocking": false,
                "from": "2026-01-15",
                "canceled": false,
                "constraintGroup": "Contract",
                "nature": "CONTRACT_TYPE"
            }
        ]
    }
]

Details

from: contract start date in yyyy-MM-dd format.
to: contract end date in yyyy-MM-dd format. This field is not returned if the contract is still active at the time of the request.
regularMinutes: regular hours (in minutes) established in the contract. The value is interpreted based on the defined time base: annual, weekly, or daily.
weeklyContract: whether the contract is defined weekly (true) or annually (false).
dailyContract: whether the contract is defined on a daily basis. If the contract is neither daily nor weekly, it is considered annual.
countingDays: for daily contracts, indicates which days are counted as working days. Possible values are 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 regular working hours. Possible values are WEEKLY, MONTHLY, YEARLY, or PERIODS.
regularPeriodMultiplier: multiplier index for the regularControlPeriod. For example, a value of 2 with a weekly control period would define a biweekly cycle.
regularPeriodStartDate: start date of the regularControlPeriod in yyyy-MM-dd format. This is only relevant if regularPeriodMultiplier is greater than 1; otherwise, it is ignored.
additionalControlPeriod: control period for additional hours. Possible values are WEEKLY, MONTHLY, YEARLY, or PERIODS.
additionalPeriodMultiplier: multiplier index for the additionalControlPeriod. For example, a value of 2 with a weekly control period would define a biweekly cycle.
additionalPeriodStartDate: start date of the additionalControlPeriod in yyyy-MM-dd format. This is only relevant if additionalPeriodMultiplier is greater than 1; otherwise, it is ignored.
calendarDaysOff: whether vacation days are processed as calendar days (true) or business days (false).
numberOfHolidays: number of vacation days included in the employee’s contract.
numberOfPublicHolidays: number of public holidays included in the employee’s contract.
weeklyDaysInvolved: working days of the week. Possible values are MONDAY_SUNDAY, MONDAY_SATURDAY, LABOR_DAYS, LABOR_MONDAY_SATURDAY, or WEEKENDS_AND_HOLIDAYS.
metadata: any additional data related to the contract that has been pre-configured. The structure of these metadata depends on the business configuration.
costPerHour: hourly cost of the employee.
personCategory: external identifier of the employee’s category.
employeeId: external identifier of the employee.
id: external identifier of the contract.
contractTypeName: name of the contract type applied.
completed: indicates whether the contract is finalized or not.
constraints: list of constraints applied to the contract.
- id: unique identifier of the constraint in the system.
- parameters: object that groups the configurable values specific to each constraint. The set of keys, their data types, and validation rules are defined independently for each constraint type.
- 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 (true) or not (false).
- from: date from which the constraint is active, in yyyy-MM-dd format.
- canceled: indicates whether the constraint has been canceled (true) or is still active (false).
- constraintGroup: origin of the constraint. Since these are the contract’s own constraints, its value will always be Contract in this endpoint.
- nature: nature of the constraint according to how it was entered. The possible values are PERSONAL (entered manually) and CONTRACT_TYPE (applied from a contract type or an import).

The nature field only applies to contract constraints, which are the ones returned by this endpoint. Exceptional constraints do not have this field.

The response will contain the data defined for each contract. For example, if no contract type has been applied, contractTypeName will not appear in the response. Likewise, if a contract has no associated constraints, the constraints array will appear empty [].

Considerations

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

If the employee has no contracts overlapping the indicated date range, the request will return an empty array [].

The from and to parameters are required. All contracts overlapping that range are returned, not just those starting within it.

Useful links

What is a contract? And a contract type?

What is a constraint?

How to query the constraints catalog?

How to apply a contract type?