Create or update employee list (complex)

This endpoint is one of the most complex endpoints in Orquest. It not only allows creating or modifying the employee list itself but also all associated data such as users, contracts, service associations, etc.

PUT /api/v2/businesses/{businessId}/employees

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",
"lag": 0,
"partial": true,
"ignoreWithoutOuterId": false,
"ignoreServiceAssociations": false,
"ignoreContracts": false,
Details

  • business*. External identifier configured in Orquest for the business.

  • lag*. Number of days prior to the current date that are considered when processing the request.

  • partial. Determines whether the information applied by the contract types should be reset. It is recommended to always enable this.

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

  • ignoreServiceAssociations. Determines whether the employee’s service associations are updated. If set to true, no service association information needs to be included in the request.

  • ignoreContracts. Determines whether the employee’s contracts are updated. If set to true, no contract information needs to be included in the request.

Object person*

Contains the personal data of the employee identified by their employeeId.

 
"person": {
      "name": "string",
      "surname": "string",
      "group": "string",
      "email": "string",
      "birthday": "yyyy-MM-dd",
      "employeeId": "string",
      "metadata": {},
      "seniority": "yyyy-MM-dd",
      "virtual": false
    }
Details

  • name*. Employee’s first name.

  • surname*. Employee’s last name(s).

  • group. Group the employee belongs to.

  • email. Employee’s email address, in the correct format.

  • birthday. Date of birth in yyyy-MM-dd format.

  • employeeId*. Employee identifier in the external system.

  • metadata. Additional data about the employee. The structure of this field must be previously configured at the business level by the Orquest team.

  • seniority. Employee’s seniority date in yyyy-MM-dd format.

  • virtual. Determines whether this is a real employee or a virtual one used, for example, to run simulations.

Object user

Contains the data that links the employee to an Orquest application user.

 
"user": {
      "username": "string",
      "email": "string",
      "nodes": [
        0
      ],
      "roles": [
        "string"
      ]
    }
Details

  • username*. Username. Must be unique.

  • email*. User’s email address. Must be unique.

  • nodes. List of internal Orquest identifiers for the nodes where the user will have visibility. If no node is specified, the user will be linked to the business root node. Nodes can be consulted here.

  • roles. List of roles applied to the user. These roles are configured at the business level.

Object serviceAssociations

Contains information about the service associations established for the employee.

 
"serviceAssociations": [
      {
        "ownerProduct": "string",
        "product": "string",
        "from": "yyyy-MM-dd",
        "to": "yyyy-MM-dd",
        "splitPresence": true,
        "unplannable": true,
        "card": "string",
        "roles": [
          "string"
        ],
        "disponibility": [
          {
            "from": "yyyy-MM-dd",
            "to": "yyyy-MM-dd",
            "ranges": [
              {
                "dayType": "string",
                "startMinuteDay": 0,
                "duration": 0
              }
            ],
            "type": "Enum",
            "timeFramePatternId": "string",
            "weekStart": 0,
            "blockedType": "Enum"
          }
        ],
        "regularCessions": [
          {
            "product": "string",
            "minutes": 0,
            "days": [
              "Enum"
            ]
          }
        ],
        "metadata": {},
        "id": "string"
      }
    ]
Details

  • ownerProduct*. External identifier of the product or section the employee belongs to.

  • product*. External identifier of the product or section where the employee will work. It can be the same as ownerProduct; if different, it represents a cession.

  • from*. Start date of the service association in yyyy-MM-dd format.

  • to. End date of the service association in yyyy-MM-dd format. Can be null, indicating no end date has been set.

  • splitPresence. Determines whether this is a split shift. The default value is true.

  • unplannable. Determines whether the employee will be ignored by the scheduler and must therefore be planned manually. The default value is false.

  • card. Identifier of the employee’s card in time-tracking systems.

  • roles. List of role identifiers assigned to the employee in this service association.

  • disponibility. Employee availability during a specific interval. If not defined, the employee’s availability is total. To change it, the following information must be provided.

    • from*. Start date of the availability period in yyyy-MM-dd format.

    • to. End date of the availability period in yyyy-MM-dd format. It can be null as long as the service association also does not have an end date.

    • ranges*. List of availabilities by day type. For each type, include the following information:

      • dayType*. Day type to which the availability applies. It can be a system day type (ALL, WEEKENDS, MONDAY, TUESDAY, WEDNESDAY, etc.) or one defined at the business level.

      • startMinuteDay*. Start of availability in minutes from 00:00 local time. For example, 600 for 10:00.

      • duration*. Duration of the range in minutes.

    • type. Effective availability type: DAY_TYPE, SHIFT_PATTERN or CALENDAR.

    • timeFramePatternId. Internal identifier of the applied shift or availability pattern. Only for SHIFT_PATTERN availability type.

    • weekStart. Start week. Only for SHIFT_PATTERN availability type.

    • blockedType. Type of block applied to the pattern (NONE, EXTENSIBLE_WORK, NON_EXTENSIBLE_WORK, EXTENSIBLE_TIME, NON_EXTENSIBLE_TIME, DAILY_WORKED, FREE, WORKING_HOURS). Only for SHIFT_PATTERN availability type.

  • regularCessions. Determines whether the employee works systematically on some days of the week in another product or section. If regular cessions exist, they are defined using the following fields:

    • product*. External identifier of the destination product or section where the employee will work.

    • minutes*. Number of minutes the employee will work at the destination product or section.

    • days*. List of day types on which the employee will work on cession. Possible values: MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY.

  • metadata. Any additional data related to the service association. The structure of this metadata must be previously configured by the Orquest team.

  • id. External identifier of the service association. Must be unique.

Object contracts

Contains information about the contracts applied to the employee, in terms of hours worked, labour limitations, etc.

 
"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"
      }
    ]
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 hours in the contract are defined on a weekly basis (true).

  • dailyContract. Determines whether the regular hours in the contract 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 indicate a two-week period. Its default value is 1 and 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 value 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 indicate a two-week period. Its default value is 1 and 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 value 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 has been settled or not. If true is sent along with the contract end date, it will be considered settled on that date; if no end date is included, the contract will be considered settled on the date of the request.

  • additionalDailyContract. Determines whether the additional hours in the contract are defined on a daily basis (true).

  • additionalWeeklyContract. Determines whether the additional hours in the contract are defined on a weekly basis (true). If both additionalWeeklyContract and additionalDailyContract are sent as false, the contract additional hours are assumed to be annual.

  • regularCountingDayType. Day type set for the regular hours of a daily contract. It can be a system day type (ALL, WEEKENDS, MONDAY, TUESDAY, WEDNESDAY, etc.) or one defined at the business level.

  • additionalCountingDayType. Day type set for the additional hours of a daily contract. It can be a system day type (ALL, WEEKENDS, MONDAY, TUESDAY, WEDNESDAY, etc.) or one defined at the business level.

Request example

After analyzing the different fields, an example of the request body is shown:

[
    {
        "business": "BUSINESSID",
        "lag": 0,
        "partial": false,
        "ignoreWithoutOuterId": false,
        "ignoreServiceAssociations": false,
        "ignoreContracts": false,
        "person": {
            "name": "Eva",
            "surname": "García",
            "birthday": "1987-05-07",
            "employeeId": "170326",
            "virtual": false
        },
        "user": {
            "username": "egarcia",
            "email": "egarcia@mail.com",
            "nodes": [
                10101
            ],
            "roles": [
                "Manager"
            ]
        },
        "serviceAssociations": [
            {
                "ownerProduct": "0001-G",
                "product": "0001-G",
                "from": "2026-01-01",
                "to": null,
                "disponibility": [
                    {
                        "from": "2026-01-01",
                        "ranges": [
                            {
                                "dayType": "ALL",
                                "startMinuteDay": 0,
                                "duration": 1440
                            }
                        ],
                        "type": "SHIFT_PATTERN",
                        "timeFramePatternId": "d01e1e08-b2e4-48d1",
                        "weekStart": 1,
                        "blockedType": "NON_EXTENSIBLE_TIME"
                    }
                ]
            }
        ],
        "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"
            }
        ]
    }
]

Considerations

Each entity in the list has its own status; therefore, each element is updated independently.

A maximum of 30 elements is allowed in the request body.

User validation

When data from the user object is included, the system validates whether the user exists in Orquest. The following scenarios are possible:

  • If the user does not exist, it is created and linked to the employee.

  • If the user exists and is already linked to the employee in the request, its information is updated. The username field is not updated; only email, nodes, and roles can be modified.

  • If the user exists and is linked to another employee, the operation is cancelled, and the request returns a 409 Conflict error.

If the email address format is invalid, the request returns a 406 Not Acceptable error with the message User email is not valid.

In the roles field, the role name must exactly match one defined in the system under Business Configuration > Roles. If any of the roles do not match those defined at the business level, the request returns a 409 Conflict error with the message some role is not valid.

Previously defined nodes and roles remain unchanged when the request is made without including these user fields.

An integration user can assign any role defined at the business level.

If the employee category (personCategory) specified in the request body does not exist in the system, a new category is automatically created (Business configuration > Employee categories). In this case, the name and external identifier of the new category will match the value provided in this field. Therefore, it is recommended to review existing categories before making the request to avoid unnecessary creation of additional categories.

Useful links

What is an employee?

What is a service association?

What is a contract? And a contract type?

How to integrate employees?