Integrating employees

What are employees?

As detailed here, employees are individuals hired to perform specific work within a business. The information related to employees includes all data concerning assignments, skills, clockins, contracts, service associations, requests and incidences.

What endpoints are available?

To integrate employees through the API, there are four endpoints available, organized across two dimensions: whether a single employee or a list is being integrated, and whether the full set of fields or only the essential data is needed.

Individual List

Simple

PUT /simple/employee

PUT /simple/employees

Complex

PUT /employee

PUT /employees

All endpoints share the base fields for person, contracts and service associations. Complex ones extend that set with:

  • lag parameter (required): allows sending only the information for the affected period without overwriting the rest.

  • Behavior flags: partial, ignoreContracts, ignoreServiceAssociations, ignoreWithoutOuterId.

  • Additional person fields: metadata, virtual.

  • Linked user (user): creates or updates the Orquest access user associated with the employee.

  • Additional service association fields: card, roles, regularCessions, metadata.

  • Additional contract fields: weeklyContract, dailyContract, regularPeriodMultiplier, regularPeriodStartDate, additionalPeriodMultiplier, additionalPeriodStartDate, completed, additionalDailyContract, additionalWeeklyContract, regularCountingDayType, additionalCountingDayType.

To send only the information for a specific period without overwriting existing data, it is recommended to use a complex endpoint with lag > 0.

Operations

The integration API allows managing an employee’s lifecycle within Orquest: onboarding, transfers, contract updates, etc. The most common operations are detailed below.

Adding an employee

Adding an employee in Orquest typically includes three blocks of information: personal data, service associations and contracts.

For the employee to be schedulable from the first day, the request must include both a service association and an active contract: without a service association, the employee does not appear in the service and cannot receive shifts; without an active contract, the employee cannot be scheduled even if the association is active.

The service association links the employee to a product (section), so the product must have an external identifier defined in Orquest beforehand for the request to succeed: Store Configuration > Products > Outer ID.

The flow to add an employee is as follows:

  1. Choose the endpoint based on the need: complex/simple and list/individual.

  2. Build the request with the three recommended blocks and their respective required fields.

    • person: name, surname, employeeId.

    • serviceAssociations: at least ownerProduct, product and from.

    • contracts: at least from and the rest of the required fields depending on the request.

  3. Send the request and check the API response.

Without a service association, the employee will only appear in the root node of the business and will not be visible or schedulable in any service.
Transferring an employee

There are three types of transfers related to the employee’s service association:

Permanent transfer to another product

Involves adding a new service association to the destination product and closing the previous one. The request body must include the updated serviceAssociations object:

  1. End date (to) of the current association.

  2. New service association with the corresponding ownerProduct and product.

Cession

Involves adding a service association where the origin (ownerProduct) is kept but the destination (product) is changed. The cession must start and end within the interval of the main service association.

The request is built by including the existing service association and the cession as a second entry in serviceAssociations, with ownerProduct pointing to the original product and product to the destination product, and with from and to dates within the period of the main association.

"serviceAssociations": [
    {
        "ownerProduct": "0001-G",
        "product": "0001-G",
        "from": "2025-01-01",
        "to": null
    },
    {
        "ownerProduct": "0001-G",
        "product": "0002-G",
        "from": "2026-03-01",
        "to": "2026-03-31"
    }
]

Regular cession

Involves the employee working on a recurring basis in another product on the same days and for the same amount of time. It is configured via the regularCessions field within the main service association, available only in complex endpoints.

The request is built by including the service association with the regularCessions field, the destination product (product), the days of the week (daysOfWeek) and the dedication in minutes (minutes).

"serviceAssociations": [
    {
        "ownerProduct": "0001-G",
        "product": "0001-G",
        "from": "2025-01-01",
        "regularCessions": [
            {
                "product": "0003-G",
                "minutes": 240,
                "daysOfWeek": ["WEDNESDAY"]
            }
        ]
    }
]
Removing an employee

The API does not allow deleting employees from the system, so offboarding is done by closing the employee’s relationship with the business: without an active service association, the employee is no longer visible or schedulable in the service; without an active contract, the employee can no longer receive shifts. This way, the historical record is kept intact.

In the request, the to field must be set with the end date of the service association and the contract as appropriate.

The employee remains in the system with their historical data, which allows consulting their past activity even if they are no longer active.
Updating a contract

To modify the data of an existing contract, simply include the contract with the updated fields in the request. If the employee has more than one contract, all contracts can be included in the request or complex endpoints with lag > 0 can be used to limit the affected period.

To end a contract there are two options:

  • Set the to field with the end date: available in all endpoints.

  • Set the completed field to true: available only in complex endpoints. If true is sent along with the contract end date, the contract will be considered settled on that date; if no end date is included, the contract will be considered settled on the request date.

To add a new contract to an employee who already has contracts, include it alongside the existing ones (simple or complex requests with lag = 0) or send only the new one with lag adjusted to its validity period (complex endpoints only).

Updating availability

The disponibility field defines, within a service association or cession, the employee’s availability over a specific period.

"serviceAssociations": [
    {
        "ownerProduct": "0001-G",
        "product": "0001-G",
        "from": "2021-06-25",
        "to": null,
        "disponibility": [
            {
                "from": "2021-06-25",
                "to": "2023-06-01",
                "ranges": [
                    {
                        "dayType": "ALL",
                        "startMinuteDay": 600,
                        "duration": 600,
                        "available": true
                    },
                    {
                        "dayType": "MONDAY",
                        "startMinuteDay": 0,
                        "duration": 1440,
                        "available": false
                    }
                ]
            },
            {
                "from": "2026-01-01",
                "ranges": [
                    {
                        "dayType": "ALL",
                        "startMinuteDay": 0,
                        "duration": 1440,
                        "available": true
                    }
                ],
                "type": "SHIFT_PATTERN",
                "timeFramePatternId": "d01e1e08-b2e4-48d1",
                "weekStart": 1,
                "blockedType": "NON_EXTENSIBLE_TIME"
            }
        ]
    }
]

This will generate two availability intervals:

  • From 2021-06-25 to 2023-06-01: available every day (ALL) from 10:00 to 20:00 local time, unavailable on Mondays (MONDAY).

  • From 2026-01-01: effective availability according to the shift pattern corresponding to the ID in the request.

To delete existing availability, send an empty array: "disponibility": [].

If null is sent or the field is not included, the previously defined availability remains in the system.

All endpoints support this operation, both simple and complex.

Overlapping intervals are not allowed for the same type of entity. Therefore, service associations, contracts or availability periods with overlapping dates cannot coexist.

FAQ

How to choose the correct endpoint?

It is recommended to use the matrix in the What endpoints are available? section as a quick reference. Some tips:

  • When it is necessary to send the linked user’s data or use the lag parameter: use a complex endpoint.

  • When only personal data, contracts and associations are needed: any endpoint is valid, but simple ones require fewer fields.

  • If integrating several employees at once: use list endpoints.

  • If it is necessary to use behavior flags: use a complex endpoint.

What happens if an employee is created without a service association?

The employee will only appear in the main business node. To retrieve the employee, there are two options:

  • Use any of the available endpoints to modify the employee’s data and add a service association.

  • Link the employee from the graphical user interface: Organizational Diagram > People > View Unassigned Employees > Retrieve Employee.

How does the lag parameter work in requests?

The lag parameter determines the number of days prior to the request date that will be considered when managing information in Orquest. For more information on its behavior, it is recommended to visit the following link, where explanatory examples are provided.

How to apply a contract type?

To apply a contract type, the contractTypeId field must be included within the contracts object, considering the following conditions:

  • Orquest DOES NOT apply contract types to contracts whose end date is earlier than the current system date.

  • The contract type ID must match the one configured at the business level: Organizational Diagram > Contract types > Outer ID.

  • Manually defined restrictions disappear when a contract type is applied.

If applicable, the following contract fields are overwritten with the values set for the contract type:

  • regularMinutes

  • additionalMinutes

  • numberOfHolidays

  • numberOfPublicHolidays

If any value other than 0 is provided, the request information takes precedence, even if a contract type is applied. For example, if the contract type has no vacation days but the request includes "numberOfHolidays": 7, the contract type will be applied, and 7 vacation days will be set.

The remaining required fields —depending on the request— must be submitted, and the specified value will be applied.

After integrating a contract via API with an associated contract type, manual changes made through the Orquest interface may cause the contract type to no longer apply. Specifically, the contract type will be removed if any field is manually modified within the following sections:

  • Contract definition.

  • Control period (Expiration).

  • Holidays.

If contract metadata has been created for the business, modifying any of it will also cause the previously applied contract type to disappear.

What happens if an employee that already exists in the system is sent?

As long as the employee’s external identifier matches, the request will update the employee’s data with the information sent. If the lag parameter is included with a value greater than 0, only the information for the covered period will be modified. If lag = 0 or a simple endpoint is used, all employee data for the current period will be overwritten.

Sending incomplete information with lag = 0 may delete existing data. It is recommended to always send complete information or use lag in a controlled manner.
How are employee categories managed?

When an employee category that does not exist in the system is sent, Orquest automatically creates a new category whose name and external identifier match the value of personCategory specified in the request body.

However, it is possible to configure this behavior at the business level to prevent automatic creation and have the API return an error instead, avoiding the generation of duplicates.

To change the default behavior, it is necessary to notify the Orquest team so they can make the change in the business configuration.

To maintain a clean integration flow, it is recommended to:

  1. Check the employee categories available in the business.

  2. Send the external identifier (not the name) of the category in the personCategory field of the employee’s contracts.

Common errors

Message Meaning Recommended solution

cession_no_contained_in_association

Some cessions are not contained within a service association.

Verify that the cession dates are within the range of the corresponding service association.

contract_overlapped

Some contracts are overlapped.

Review the start and end dates of the contracts and ensure their periods do not overlap.

User email is not valid

The email address is not valid.

Check the email format (it must follow the RFC 5321 standard).

role_not_valid

The role is either invalid or does not exist.

Verify that the role sent is configured in the Orquest business.

Service or node forbidden

The service does not exist or has not been indicated.

Check that the service identifier sent exists in Orquest.

ContractType [] not found in business

The contract type does not exist.

Verify that the external identifier of the contract type is valid and configured.

not_valid_metadata

The metadata is not valid, either due to structure or configuration.

Check that the metadata sent matches the business configuration in Orquest.

overlapped_associations

Some service associations are overlapped.

Review the start and end dates of the associations and ensure they do not overlap for the same product.

interval_disponibility_out_of_association

The availability interval is not contained within the service association.

Ensure that the availability interval dates are within the service association dates.

interval_day_overlapped

Some availability intervals are overlapped.

Review the availability ranges and remove overlaps between intervals.