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

Unlike the complex list, here the validation is performed as a block: if any element of the list fails its validation, none of them is imported, not just the invalid element.

An empty list body ([]) is valid and does nothing, returning 200 OK.

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.

Error codes

Since validation happens as a block, if any element of the list incurs any of the codes in this table, the entire response is 406 Not Acceptable with the list of errors per element, and none of the request’s data is saved.

In addition to the common errors, this endpoint can return the following codes:

Code Message Description

400 Bad Request

-

The request body is not valid JSON or cannot be read.

Time frame patter not found

The shift pattern identifier (timeFramePatternId) sent in a service association is invalid. It is recommended to check the shift patterns available for the service’s employees.

Calendar disponibility type is not enabled for business

The CALENDAR availability type is sent in a service association without the business having it enabled.

ContractType not found in business

The contract type identifier (contractTypeId) sent in a contract is invalid. It is recommended to check the contract types defined at service level.

406 Not Acceptable

-

A field marked as required is missing within an object present in the request (person, a contract, a service association…​).

-

A numeric field receives a negative value.

-

In a contract or a service association, the start date (from) is later than the end date (to).

-

The value of an enumerated field does not match any of the defined values.

-

The list sent exceeds the allowed limit of 30 elements. It is recommended to split the request into smaller batches.

The person object itself must be present in the body: if it is omitted entirely (or arrives as null), the request does not return the expected 406.

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.

Useful links

What is an employee?

What is a service association?

What is a contract? And a contract type?

How to integrate employees?