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

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

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.

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

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

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

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

Code Message Description

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.

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 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?