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

A detailed explanation of each field that can make up the request body is provided below.

Required fields are marked with (*).

Accepted values for Enum type fields are shown in the collapsible details.

Request body

JSON analysis

Object person*

Contains the personal data of the employee identified by their employeeId.

 
"person": {
      "name": "string",
      "surname": "string",
      "group": "string",
      "email": "string",
      "birthday": "yyyy-MM-dd",
      "employeeId": "string",
      "seniority": "yyyy-MM-dd"
    }
Details

  • name*: employee’s first name.

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

  • group: group the employee belongs to.

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

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

  • employeeId*: employee identifier in the external system.

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

Object serviceAssociations

Contains information about the service associations established for the employee.

 
"serviceAssociations": [
      {
        "ownerProduct": "string",
        "product": "string",
        "from": "yyyy-MM-dd",
        "to": "yyyy-MM-dd",
        "splitPresence": true,
        "unplannable": true,
        "disponibility": [
          {
            "from": "yyyy-MM-dd",
            "to": "yyyy-MM-dd",
            "ranges": [
              {
                "dayType": "string",
                "startMinuteDay": 0,
                "duration": 0,
                "available": true
              }
            ],
            "type": "Enum",
            "timeFramePatternId": "string",
            "weekStart": 0,
            "blockedType": "Enum"
          }
        ],
        "id": "string"
      }
    ]
Details

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

  • product*: external identifier of the product or section where the employee will work. It can be the same as ownerProduct; if different, it represents a cession.

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

  • to: end date of the service association in yyyy-MM-dd format. Can be null, indicating no end date has been set.

  • splitPresence: determines whether this is a split shift. The default value is true.

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

  • disponibility: employee availability during a specific interval. If not defined, the employee’s availability is total. To change it, the following information must be provided.

    • 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 also does not have an end date.

    • ranges: list of availabilities by day type. For each type, include the following information:

      • dayType*: day type to which the availability applies. It can be a system day type (ALL, WEEKENDS, MONDAY, TUESDAY, WEDNESDAY, etc.) or one defined at the business level.

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

      • duration*: duration of the range in minutes.

      • available: indicates whether the employee is available (true) or not available (false) for the given range and day type. The default value is true.

    • type: effective availability type: DAY_TYPE, SHIFT_PATTERN or CALENDAR.

    • timeFramePatternId: internal identifier of the applied shift or availability pattern. Only for SHIFT_PATTERN availability type.

    • weekStart: start week. Only for SHIFT_PATTERN availability type.

    • blockedType: type of block applied to the pattern (NONE, EXTENSIBLE_WORK, NON_EXTENSIBLE_WORK, EXTENSIBLE_TIME, NON_EXTENSIBLE_TIME, DAILY_WORKED, FREE, WORKING_HOURS). Only for SHIFT_PATTERN availability type.

  • id: external identifier of the service association. Must be unique.

Object contracts

Contains information about the contracts applied to the employee, in terms of hours worked, labour limitations, etc.

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

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

  • to: contract end date in yyyy-MM-dd format. Can be sent as null if no end date has been set.

  • regularMinutes*: regular hours (in minutes) established in the contract. The value is interpreted based on the defined time base: annual, weekly, or daily.

  • countingDays: in a daily contract, indicates which days count as worked. Its value can be MONDAY_SUNDAY, MONDAY_SATURDAY, LABOR_DAYS, LABOR_MONDAY_SATURDAY or WEEKENDS_AND_HOLIDAYS.

  • additionalMinutes*: complementary hours (in minutes) established in the contract. The value is interpreted based on the defined time base: annual, weekly, or daily.

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

  • additionalControlPeriod*: control period for complementary hours. Can be WEEKLY, MONTHLY, YEARLY or PERIODS.

  • calendarDaysOff*: determines whether holidays will be processed as calendar days (true) or working days (false).

  • numberOfHolidays*: number of holiday 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 (week type). This field can be defined as MONDAY_SUNDAY, MONDAY_SATURDAY, LABOR_DAYS, LABOR_MONDAY_SATURDAY or WEEKENDS_AND_HOLIDAYS.

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

  • costPerHour: employee’s cost per hour worked.

  • personCategory*: external identifier of the employee’s category. Can be consulted here.

  • id: external identifier of the contract. Must be unique. Limited to 200 characters.

  • contractTypeId: identifier of the contract type to be applied. If included, the contract’s characteristics will be overridden by those of the contract type (more information here). If not specified, contract type filters may be applied to assign one.

Request example

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

[
    {
        "person": {
            "name": "Jane",
            "surname": "Santos",
            "employeeId": "010203",
            "seniority": "2018-03-01"
        },
        "serviceAssociations": [
            {
                "ownerProduct": "0001-G",
                "product": "0001-G",
                "from": "2024-01-01",
                "to": null,
                "disponibility": [
                    {
                        "from": "2026-01-01",
                        "ranges": [
                            {
                                "dayType": "ALL",
                                "startMinuteDay": 0,
                                "duration": 1440,
                                "available": false
                            }
                        ],
                        "type": "SHIFT_PATTERN",
                        "timeFramePatternId": "d01e1e08-b2e4-48d1",
                        "weekStart": 1,
                        "blockedType": "NON_EXTENSIBLE_TIME"
                    }
                ]
            }
        ],
        "contracts": [
            {
                "from": "2026-01-01",
                "to": null,
                "regularMinutes": 0,
                "additionalMinutes": 0,
                "regularControlPeriod": "WEEKLY",
                "additionalControlPeriod": "WEEKLY",
                "calendarDaysOff": false,
                "numberOfHolidays": 0,
                "numberOfPublicHolidays": 0,
                "weeklyDaysInvolved": "MONDAY_SUNDAY",
                "personCategory": "AV",
                "contractTypeId": "JC40"
            }
        ]
    }
]

Considerations

If the request body is not valid JSON or cannot be read, the request will return a 400 Bad Request error.

If a field marked as required is not provided, the request will return a 406 Not Acceptable error.

If a numeric field receives a negative value, the request will return a 406 Not Acceptable error.

In contracts and service associations, if the start date (from) is later than the end date (to), the request will return a 406 Not Acceptable error.

If the value of an enumerated field does not match any of the defined values, the request will return an error.

It is recommended to review the response body in case of an error, as it includes relevant information for diagnosis and debugging, such as invalid fields or unrecognized values.

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.

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?