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

Here is a detailed explanation of each of the fields that can comprise the request body, with some of them being mandatory for the request to be successful.

Mandatory fields are marked with an asterisk (*).

Request body

JSON Analysis 
"business": "string",
"lag": 0,
"partial": true,
"ignoreWithoutOuterId": false,
"ignoreServiceAssociations": false,
"ignoreContracts": false,
Details

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

  • lag*: number of days prior to the current date considered when managing the request.

  • partial: determines if the information applied by contract types should be reset. It is recommended to always activate it.

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

  • ignoreServiceAssociations: determines if employee service associations are updated. If set to true, it is not necessary to add information about service associations in the request.

  • ignoreContracts: determines if employee contracts are updated. If set to true, it is not necessary to add information about contracts in the request.

Object person*

Includes the personal data of the employee identified through their employeeId.

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

  • name*: employee’s name.

  • surname*: employee’s surname(s).

  • group: if groups have been defined within the business, the group to which the employee belongs.

  • email: the employee’s email, in the correct format.

  • birthday: the employee’s date of birth in the format yyyy-MM-dd.

  • employeeId*: employee’s identifier in the external system.

  • metadata: additional data about the employee. The structure of this field must be previously configured at the business level.

  • seniority: employee’s seniority in the format yyyy-MM-dd.

  • virtual: determines whether it is a real employee or a virtual one used, for example, for simulations.

Object user

Includes the data linking the employee to a user in the Orquest application.

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

  • username*: user’s name. It must be unique.

  • email*: user’s email. It must be unique.

  • nodes: list (array) of Orquest node identifiers where the employee will have access as a user. If they have access to the root node, they will by default have access to the rest of the nodes in the organizational tree.

  • roles: list (array) of roles to be assigned to the user once created. These roles are configured at the business level.

Object serviceAssociations

Includes information regarding service associations established for the employee.

 
"serviceAssociations": [
      {
        "ownerProduct": "string",
        "product": "string",
        "from": "string",
        "to": "string",
        "splitPresence": true,
        "unplannable": true,
        "card": "string",
        "roles": [
          "string"
        ],
        "disponibility": [
          {
            "from": "string",
            "to": "string",
            "ranges": [
              {
                "dayType": "string",
                "startMinuteDay": 0,
                "duration": 0
              }
            ]
          }
        ],
        "regularCessions": [
          {
            "product": "string",
            "minutes": 0,
            "days": [
              "string"
            ]
          }
        ],
        "metadata": {},
        "id": "string"
      }
    ]
Details

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

  • product*: identifier of the product or section where the employee will work. It can be the same as ownerProduct.

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

  • to: end date of the service association in yyyy-MM-dd format. It can be null, indicating no end date is set.

  • splitPresence: determines if it is a split shift. The default value is true.

  • unplannable: determines if the employee will be ignored by the scheduler, so they must be planned manually. The default value is false.

  • card: identifier of the employee’s card in time clock systems.

  • roles: list (array) of role identifiers to be assigned to the employee in this service association.

  • disponibility: employee’s availability depending on the type of day during a specific period. If not defined, the employee’s availability by default is 24/7, considering the constraints of their contract. To change it, the following data must be sent:

    • 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 set to null as long as the service association is also null.

    • ranges*: list (array) of availabilities for each type of day. These ranges must be defined in the contract and include the following parameters:

      • dayType*: type of day to which the availability applies. The available system options are: ALL, WEEKENDS, WORKED, HOLIDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY. However, other types of days can be defined at the business level.

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

      • duration*: duration of the range in minutes.

  • regularCessions: determines if the employee works some days a week in another product or section systematically. If there are regular cessions, they must be defined through the following fields:

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

    • minutes*: number of minutes the employee will work in the destination product or section.

    • days*: list (array) of day types the employee will work on loan.

  • metadata: any additional data related to the service association. The structure of this metadata must be previously configured.

  • id: identifier of the service association in the external system.

Object contracts

Includes information regarding the contracts that apply to the employee, in terms of working hours, labor restrictions, etc.

 
"contracts": [
      {
        "from": "string",
        "to": "string",
        "regularMinutes": 0,
        "weeklyContract": true,
        "dailyContract": true,
        "countingDays": "string",
        "additionalMinutes": 0,
        "regularControlPeriod": "string",
        "regularPeriodMultiplier": 1,
        "regularPeriodStartDate": "string",
        "additionalControlPeriod": "string",
        "additionalPeriodMultiplier": 1,
        "additionalPeriodStartDate": "string",
        "calendarDaysOff": true,
        "numberOfHolidays": 0,
        "numberOfPublicHolidays": 0,
        "weeklyDaysInvolved": "string",
        "metadata": {},
        "costPerHour": 0,
        "personCategory": "string",
        "id": "string",
        "contractTypeId": "string",
        "completed": true
      }
    ]
Details

  • from*: start date of the contract in yyyy-MM-dd format.

  • to: end date of the contract in yyyy-MM-dd format. It can be sent as null if there is no specified end date.

  • regularMinutes*: number of minutes expected for the employee to work according to the terms of their employment contract. This field depends on the control period set for the contract: annual, weekly, or daily.

  • weeklyContract*: determines if the contract is defined on a weekly (true) or annual (false) basis.

  • dailyContract: determines if the contract is defined on a daily basis. 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 or LABOR_DAYS.

  • additionalMinutes*: number of additional minutes the employee can work according to the terms of their employment contract, exceeding the regular time. This field depends on the control period set for the contract: annual, weekly or daily.

  • regularControlPeriod*: control period for regular hours established in the contract. It can be WEEKLY, MONTHLY or YEARLY.

  • regularPeriodMultiplier: multiplier index for regularControlPeriod. For example, if set to 2 with a weekly regularControlPeriod, it would indicate a bi-weekly period. Its default value is 1, and it accepts null or any integer equal to or greater than 1.

  • regularPeriodStartDate: start date of regularControlPeriod in yyyy-MM-dd format. This date is considered for a regularPeriodMultiplier value greater than 1; if the multiplier value is equal to 1, the date is ignored.

  • additionalControlPeriod*: control period for additional hours. It can be WEEKLY, MONTHLY or YEARLY.

  • additionalPeriodMultiplier: multiplier index for additionalControlPeriod. For example, if set to 2 with a weekly additionalControlPeriod, it would indicate a bi-weekly period. Its default value is 1, and it accepts null or any integer equal to or greater than 1.

  • additionalPeriodStartDate: start date of additionalControlPeriod in yyyy-MM-dd format. This date is considered for an additionalPeriodMultiplier value greater than 1; if the multiplier value is equal to 1, the date is ignored.

  • calendarDaysOff*: determines if holidays will be processed on natural (true) or working (false) days.

  • numberOfHolidays*: number of vacation days the employee has in their contract.

  • numberOfPublicHolidays*: number of public holidays the employee has in their contract.

  • weeklyDaysInvolved*: weekdays that will be counted. This field can be defined as MONDAY_SUNDAY or MONDAY_SATURDAY.

  • metadata: any additional data related to the contract. The structure of this metadata must be previously configured.

  • costPerHour: cost of the employee per worked hour.

  • personCategory*: external identifier of the employee’s category.

  • id: external identifier of the contract. It is highly recommended to provide this field. Otherwise, the system will attempt to match the given objects. The identification must be unique and must remain the same consistently. Limited to 200 characters.

  • contractTypeId: identifier of the contract type applied. If added, the contract’s characteristics will be overwritten by those of the contract type. If not specified, contract type filters can be applied to assign one.

  • completed: determines whether the contract is settled or not. If true and the contract end date are sent, 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.

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": "Brian",
      "surname": "Cohen",
      "group": "01",
      "email": "brian@orquest.com",
      "birthday": "1987-12-01",
      "employeeId": "021298521",
      "metadata": {
        "language": "english",
        "nationality": "scottish"
      },
      "seniority": "2021-12-01",
      "virtual": false
    },
    "user": {
      "username": "brian",
      "email": "brian@cohen.com",
      "nodes": [
        10, 14
      ],
      "roles": [
        "admin"
      ]
    },
    "serviceAssociations": [
      {
        "ownerProduct": "C14",
        "product": "C14",
        "from": "2024-04-11",
        "to": null,
        "splitPresence": true,
        "unplannable": false,
        "card": "C14A658",
        "roles": [
          "manager"
        ],
        "disponibility": [
          {
            "from": "2024-04-11",
            "to": null,
            "ranges": [
              {
                "dayType": "ALL",
                "startMinuteDay": 600,
                "duration": 300
              }
            ]
          }
        ],
        "regularCessions": [
          {
            "product": "C15",
            "minutes": 60,
            "days": [
              "MONDAY"
            ]
          }
        ],
        "metadata": {
          "restAllowed": true,
          "time": 15,
          "position": "free"
        },
        "id": "asb1415"
      }
    ],
    "contracts": [
      {
        "from": "2024-04-11",
        "to": null,
        "regularMinutes": 2400,
        "weeklyContract": true,
        "countingDays": "MONDAY_SUNDAY",
        "additionalMinutes": 360,
        "regularControlPeriod": "WEEKLY",
        "regularPeriodMultiplier": 1,
        "regularPeriodStartDate": "2024-04-11",
        "additionalControlPeriod": "WEEKLY",
        "additionalPeriodMultiplier": 1,
        "additionalPeriodStartDate": "2024-04-11",
        "calendarDaysOff": true,
        "numberOfHolidays": 25,
        "numberOfPublicHolidays": 7,
        "weeklyDaysInvolved": "MONDAY_SUNDAY",
        "metadata": {
          "full": true,
          "days": 215,
          "taxProfit": "none"
        },
        "costPerHour": 200.34,
        "personCategory": "DE125",
        "id": "321abc654def",
        "contractTypeId": "07H",
        "completed": false
      }
    ]
  }
]

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?