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

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", "aptitudes": [ { "productId": "string", "aptitudes": [ { "locationId": "string", "level": 0 } ] } ], "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. aptitudes: set of skills the employee possesses in a given product. To add aptitudes in a specific product or section, the following fields must be specified: productId*: external identifier of the product to which the aptitude is linked. aptitudes*: each of the skills defined for the employee in the indicated product. The following data must be added: locationId*: identifier of the task to which the aptitude is linked. level*: competence level in that task on a scale from 0 (not competent) to 3 (expert). 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.

"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",
      "aptitudes": [
        {
          "productId": "string",
          "aptitudes": [
            {
              "locationId": "string",
              "level": 0
            }
          ]
        }
      ],
      "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.
aptitudes: set of skills the employee possesses in a given product. To add aptitudes in a specific product or section, the following fields must be specified:
- productId*: external identifier of the product to which the aptitude is linked.
- aptitudes*: each of the skills defined for the employee in the indicated product. The following data must be added:
  - locationId*: identifier of the task to which the aptitude is linked.
  - level*: competence level in that task on a scale from 0 (not competent) to 3 (expert).
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",
      "aptitudes": [
        {
          "productId": "C14",
          "aptitudes": [
            {
              "locationId": "101",
              "level": 3
            },
            {
              "locationId": "102",
              "level": 2
            }
          ]
        }
      ],
      "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

This request will generate an atomic operation that can be automatically reverted if there are errors: the error will be displayed in the response to the request.

If data from the user object is included, the existence of that user in Orquest is validated, so the following scenarios are established:

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, the information is updated.
If the user exists and is linked to another employee, the operation is canceled and returns HTTP 409 - Conflict, indicating the conflict with error details in the response body.

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?