Get contracts by person

This endpoint returns all contracts of an employee.

GET /api/v2/businesses/{businessId}/people/{personId}/contracts

If the request parameters —both businessId and personId— are correct, the response will include the list of contracts associated with the employee, detailing the following information:

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

Below is an example of a response:

[
    {
        "from": "2024-06-25",
        "regularMinutes": 2400,
        "weeklyContract": true,
        "dailyContract": false,
        "additionalMinutes": 1200,
        "regularControlPeriod": "WEEKLY",
        "additionalControlPeriod": "WEEKLY",
        "calendarDaysOff": true,
        "numberOfHolidays": 30,
        "numberOfPublicHolidays": 14,
        "weeklyDaysInvolved": "MONDAY_SUNDAY",
        "costPerHour": 10.0,
        "personCategory": "CS",
        "employeeId": "1006350",
        "completed": false
    }
]

The response will include the data defined for each of the employee’s contracts, so some fields may be omitted. For example, if a contract type is not applied, the contractTypeName field will not appear in the response.

Considerations

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

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

Useful links

What is a contract? And a contract type?

How to apply a contract type?