Create or update employee (simplified)

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

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

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

Mandatory fields are marked with an asterisk (*).

Request body

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

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: 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 possesses in a specific 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 aptitudes defined for the employee in the specified 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 of 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 that there is no set end date.
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 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 default availability is 24/7, taking into account 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 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 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 that apply to the employee, in terms of hours worked, labor restrictions, 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 set end date.
regularMinutes*: number of minutes expected to be worked by the employee according to the terms of their employment contract. This field depends on the control period established for the contract: yearly, weekly or daily.
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 established for the contract: yearly, weekly or daily.
regularControlPeriod*: control period for 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 holidays will be processed on natural days (true) or working days (false).
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 in advance.
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 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.

Request example

Once the analysis of the various fields has been completed, an example of the request body is provided:

[
  {
    "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

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

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?