Create or update employee (complex)

This endpoint allows adding an employee or modifying their data using their identifier (employeeId). You can add or modify all employee data, including linked user, contracts, service associations, etc.

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

Below is a detailed explanation of each field that can make up the body of the request, with some fields being mandatory for a successful request.

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 that are considered when managing the request.

  • partial: determines whether to reset the information applied by the contract types. It is recommended to always enable this.

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

  • ignoreServiceAssociations: determines whether to update the employee’s service associations. If set to true, there is no need to include information about service associations in the request.

  • ignoreContracts: determines whether to update the employee’s contracts. If set to true, there is no need to include information about contracts in the request.

Object person*

Includes 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 are defined within the business, the group to which the employee belongs.

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

  • birthday: birth date in yyyy-MM-dd format.

  • employeeId*: identifier of the employee 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 yyyy-MM-dd format.

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

Object user

Includes 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. Must be unique.

  • email*: user’s email. 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 have access to the rest of the nodes in the organizational tree by default.

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

Object serviceAssociations

Includes information related to 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 established end date.

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

  • unplannable: determines whether the employee will be ignored by the planner and must be scheduled manually. The default value is false.

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

  • roles: list (array) of role identifiers 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, an employee’s default availability is 24/7, considering contract restrictions. 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 null as long as the service association is also null.

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

      • dayType*: type of day to which the availability applies. Available system options are: ALL, WEEKENDS, WORKED, HOLIDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY. However, other day types 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 assignment.

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

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

Object contracts

Includes information regarding the contracts applied to the employee, in terms of hours worked, labor limitations, 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 end date defined.

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

  • weeklyContract*: determines if the contract is defined weekly (true) or annually (false).

  • dailyContract: determines if the contract is defined daily. 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*: additional minutes the employee can work according to the terms of their employment contract that exceed the regular time. This field depends on the control period established for the contract: annual, weekly, or daily.

  • regularControlPeriod*: control period for the 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 determine it’s a biweekly period. Its default value is 1, and it accepts null or any integer greater than or equal to 1.

  • regularPeriodStartDate: start date of regularControlPeriod in yyyy-MM-dd format. This date is taken into account for a multiplier 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 determine it’s a biweekly period. Its default value is 1, and it accepts null or any integer greater than or equal to 1.

  • additionalPeriodStartDate: start date of additionalControlPeriod in yyyy-MM-dd format. This date is taken into account for a multiplier 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 business (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*: days of the week that will be counted. This field can be defined as MONDAY_SUNDAY, MONDAY_SATURDAY.

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

  • costPerHour: cost of the employee per hour worked.

  • personCategory*: external identifier of the employee category.

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

  • contractTypeId: identifier of the contract type applied. If added, the contract 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

Once the analysis of the different fields is done, 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

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?