Create or update employee list (simplified)

This endpoint is a simplified version of Create or update employee list (complex). It allows creating or modifying the list of employees including only information about the person, their service associations, and their contracts.

PUT /api/v1/businesses/{businessId}/import/simple/employees

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

Mandatory fields are marked with an asterisk (*).

Request body

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",
      "seniority": "string",
      "aptitudes": [
        {
          "productId": "string",
          "aptitudes": [
            {
              "locationId": "string",
              "level": 0
            }
          ]
        }
      ]
    }

Details

name*: employee’s name.
surname*: employee’s surname(s).
group: if business groups are defined, the group to which the employee belongs.
email: employee’s email, with correct format.
birthday: date of birth in yyyy-MM-dd format.
employeeId*: employee’s identifier in the external system.
seniority: employee’s seniority in yyyy-MM-dd format.
aptitudes: set of skills the employee has in a specific product. To add skills in a specific product or section, the following fields must be specified:
- productId*: external identifier of the product to which the skill 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 skill is linked.
  - level*: competency level in that task on a scale from 0 (not competent) to 3 (expert).

Object serviceAssociations

Includes information regarding the service associations established for the employee.

"serviceAssociations": [
      {
        "ownerProduct": "string",
        "product": "string",
        "from": "string",
        "to": "string",
        "splitPresence": true,
        "unplannable": true,
        "disponibility": [
          {
            "from": "string",
            "to": "string",
            "ranges": [
              {
                "dayType": "string",
                "startMinuteDay": 0,
                "duration": 0
              }
            ]
          }
        ],
        "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 there is no end date set.
splitPresence: determines if it is a split shift. The default value is true.
unplannable: determines if the employee will be ignored by the planner, so it must be planned manually. The default value is false.
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 restrictions 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 as null as long as the service association is also set as 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 options in the system 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 the 10:00.
  - duration*: duration of the range in minutes.
id: identifier of the service association in the external system.

Object contracts

Includes information regarding the contracts applied to the employee, in terms of working hours, labor limitations, etc.

"contracts": [
      {
        "from": "string",
        "to": "string",
        "regularMinutes": 0,
        "countingDays": "string",
        "additionalMinutes": 0,
        "regularControlPeriod": "string",
        "additionalControlPeriod": "string",
        "calendarDaysOff": true,
        "numberOfHolidays": 0,
        "numberOfPublicHolidays": 0,
        "weeklyDaysInvolved": "string",
        "metadata": {},
        "costPerHour": 0,
        "personCategory": "string",
        "id": "string",
        "contractTypeId": "string"
      }
    ]

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 set.
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.
countingDays: in a daily contract, indicates which days count as working days. 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 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.
additionalControlPeriod*: control period for additional hours. It can be WEEKLY, MONTHLY or YEARLY.
calendarDaysOff*: determines if vacations 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 previously configured.
costPerHour: cost of the employee per hour worked.
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 try to match the given objects. The identification must be unique and must be the same always. Limited to 200 characters.
contractTypeId: identifier of the contract type applied. If added, the contract characteristics will be overridden by those of the contract type. If not specified, contract type filters can be applied to assign one.

Request example

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

[
  {
    "person": {
      "name": "Brian",
      "surname": "Cohen",
      "group": "01",
      "email": "brian@orquest.com",
      "birthday": "1987-12-01",
      "employeeId": "021298521",
      "seniority": "2021-12-01",
      "aptitudes": [
        {
          "productId": "C14",
          "aptitudes": [
            {
              "locationId": "101",
              "level": 3
            },
            {
              "locationId": "102",
              "level": 2
            }
          ]
        }
      ]
    },
    "serviceAssociations": [
      {
        "ownerProduct": "C14",
        "product": "C14",
        "from": "2024-04-11",
        "to": null,
        "splitPresence": true,
        "unplannable": false,
        "disponibility": [
          {
            "from": "2024-04-11",
            "to": null,
            "ranges": [
              {
                "dayType": "ALL",
                "startMinuteDay": 600,
                "duration": 300
              }
            ]
          }
        ],
        "id": "asb1415"
      }
    ],
    "contracts": [
      {
        "from": "2024-04-11",
        "to": "2027-04-11",
        "regularMinutes": 2400,
        "countingDays": "MONDAY_SUNDAY",
        "additionalMinutes": 360,
        "regularControlPeriod": "WEEKLY",
        "additionalControlPeriod": "WEEKLY",
        "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"
      }
    ]
  }
]

Considerations

Each entity in the list has its own state, meaning each element of the list has its own set of attributes or properties that can be independently updated. No more than 30 elements are allowed in the request body.

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

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

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 details of the error 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?