Get active contracts by product

This endpoint allows retrieving all active contracts of a product.

GET /api/v2/businesses/{businessId}/products/{productId}/contracts/active

If the data included in the request is correct —both businessId and productId— the response will contain the list of active contracts within the product, that is, all contracts whose end date is equal to or later than the system’s current date.

Response example

[
    {
        "from": "2024-08-26",
        "regularMinutes": 2400,
        "weeklyContract": true,
        "dailyContract": false,
        "additionalMinutes": 1200,
        "regularControlPeriod": "WEEKLY",
        "additionalControlPeriod": "WEEKLY",
        "calendarDaysOff": true,
        "numberOfHolidays": 32,
        "numberOfPublicHolidays": 14,
        "weeklyDaysInvolved": "MONDAY_SUNDAY",
        "costPerHour": 12.0,
        "personCategory": "DV",
        "employeeId": "0001"
    },
    {
        "from": "2024-08-26",
        "regularMinutes": 1800,
        "weeklyContract": true,
        "dailyContract": false,
        "additionalMinutes": 1200,
        "regularControlPeriod": "WEEKLY",
        "regularPeriodMultiplier": 1,
        "additionalControlPeriod": "WEEKLY",
        "additionalPeriodMultiplier": 1,
        "calendarDaysOff": true,
        "numberOfHolidays": 32,
        "numberOfPublicHolidays": 14,
        "weeklyDaysInvolved": "MONDAY_SUNDAY",
        "costPerHour": 10.0,
        "personCategory": "MG",
        "employeeId": "0002",
        "contractTypeName": "Full-time"
    },
    {
        "from": "2026-01-15",
        "regularMinutes": 360,
        "weeklyContract": false,
        "dailyContract": true,
        "countingDays": "WEEKENDS_AND_HOLIDAYS",
        "additionalMinutes": 120,
        "regularControlPeriod": "YEARLY",
        "regularPeriodMultiplier": 1,
        "regularPeriodStartDate": "2026-01-15",
        "additionalControlPeriod": "YEARLY",
        "additionalPeriodMultiplier": 1,
        "additionalPeriodStartDate": "2026-01-15",
        "calendarDaysOff": true,
        "numberOfHolidays": 10,
        "numberOfPublicHolidays": 10,
        "weeklyDaysInvolved": "WEEKENDS_AND_HOLIDAYS",
        "costPerHour": 200.34,
        "personCategory": "AV",
        "employeeId": "0003",
        "completed": false
    }
]

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: number of minutes the employee is expected to work based on the terms of their employment contract. This field depends on the control period defined for the contract: 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: number of additional minutes the employee may work beyond their regular working time. This field also depends on the contract’s control period: annual, weekly, or daily.
regularControlPeriod: control period for regular working hours. Possible values are WEEKLY, MONTHLY, or YEARLY.
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, or YEARLY.
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.

The response will contain the data defined for each contract. Therefore, some fields may be present in certain contracts and absent in others.

Considerations

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

If there are no active contracts in the product, the request will return an empty array [].

Contracts whose end date is earlier than the system’s current date are excluded from the response.

If the employee has a cession, the contract will appear in the query for both products: the one they belong to and the one they have been transferred to. If the cession is regular, their contract will only appear in the query for the product they belong to.

Useful links

What is a contract? And what is a contract type?

How is a contract type applied?

What is the difference between a cession and a regular cession?