Get service associations by employee

This endpoint returns an employee’s service associations.

GET /api/v1/business/{businessId}/person/{personId}/service-associations

If the data in the request is correct —both businessId and personId— the response will contain all service associations for the employee specified.

Response example

Below is an example response:

[
    {
        "ownerProduct": "0001-G",
        "product": "0001-G",
        "from": "2021-06-19",
        "splitPresence": true,
        "unplannable": false,
        "roles": [],
        "disponibility": [
            {
                "from": "2021-06-19",
                "ranges": [
                    {
                        "dayType": "ALL",
                        "startMinuteDay": 600,
                        "duration": 600
                    },
                    {
                        "dayType": "TUESDAY",
                        "startMinuteDay": 0,
                        "duration": 1440
                    }
                ],
                "type": "DAY_TYPE"
            }
        ],
        "regularCessions": [
            {
                "product": "0003-G",
                "minutes": 240,
                "days": [
                    "TUESDAY"
                ]
            }
        ],
        "service": "0001",
        "person": {
            "name": "Olivia",
            "surname": "García",
            "group": "",
            "email": "",
            "employeeId": "1006350",
            "virtual": false
        }
    },
    {
        "ownerProduct": "0001-G",
        "product": "0002-G",
        "from": "2025-01-21",
        "to": "2025-01-28",
        "splitPresence": false,
        "unplannable": false,
        "roles": [],
        "disponibility": [
            {
                "from": "2025-01-21",
                "to": "2025-01-28",
                "ranges": [
                    {
                        "dayType": "ALL",
                        "startMinuteDay": 600,
                        "duration": 600
                    }
                ],
                "type": "DAY_TYPE"
            }
        ],
        "service": "0002",
        "person": {
            "name": "Olivia",
            "surname": "García",
            "group": "",
            "email": "",
            "employeeId": "1006350",
            "virtual": false
        }
    }
]

Details

ownerProduct*. External identifier of the product or section to which the employee belongs.
product*. External identifier of the product or section where the employee will work. It may be the same as ownerProduct; if different, it is a cession.
from*. The start date of the service association in the format yyyy-MM-dd.
to. The end date of the service association in the format yyyy-MM-dd. It can be set as null, indicating that no end date is set.
splitPresence. Determines whether it is a split shift. The default value is true.
unplannable. Determines whether the employee will be ignored by the scheduler and must be planned manually. The default value is false.
card. The employee’s card identifier in clocking systems.
roles. A list of role identifiers assigned to the employee in this service association.
disponibility. The employee’s availability during a specific interval. By default, an employee’s availability is total, considering contract limitations.
- from*. Start date of the availability interval in the format yyyy-MM-dd.
- to. End date of the availability interval in the format yyyy-MM-dd. It can be set as null if the service association also is.
- ranges*. List of availability by day type. For each type, include the following information:
  - dayType*. The type of day 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*. Availability starts in minutes from 00:00 local time. For example, 600 for 10:00.
  - duration*. The duration of the range in minutes.
- type. Effective availability type: DAY_TYPE, SHIFT_PATTERN, or CALENDAR.
- timeFramePatternId. Internal identifier of the applied shift or availability pattern. Only for SHIFT_PATTERN type.
- weekStart. Start week. Only for SHIFT_PATTERN type.
- blockedType. Blocking type applied to the pattern (NONE, EXTENSIBLE_WORK, NON_EXTENSIBLE_WORK, EXTENSIBLE_TIME, NON_EXTENSIBLE_TIME, DAILY_WORKED, FREE, WORKING_HOURS). Only for SHIFT_PATTERN type.
regularCessions. Indicates if the employee works some days of the week in another product or section systematically. If there are regular cessions, they are defined using the following fields:
- product*. External identifier of the product or section where the employee will work.
- minutes*. The number of minutes the employee will work in the product or section.
- days*. List of day types the employee will work on. Possible values: MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY.
metadata. Any additional data related to the service association. The structure of this metadata must be configured in advance by the Orquest team.
id. External identifier of the service association.
service. External identifier of the service.
person. Basic employee data:
- name. The employee’s first name.
- surname. The employee’s last name(s).
- group. If groups are defined within the business, the group to which the employee belongs.
- email. The employee’s email, if one is set.
- birthday. The birthdate in the format yyyy-MM-dd.
- employeeId. The external identifier of the employee.
- metadata. Additional data about the employee. The structure of this field must be previously configured by the Orquest team.
- seniority. The employee’s seniority date in the format yyyy-MM-dd.
- virtual. Determines whether it is a real employee or a virtual one used, for example, for simulations.

As shown in the example, the response data depends on the information defined for the employee. In this case, the employee has a service association with product 0001-G from 2021-06-19, with a regular cession of four hours on Tuesdays in 0003-G and an cession from 2025-01-21 to 2025-01-28 to product 0002-G.

Considerations

The request will return all service associations and cessions for the employee. If there are regular cessions defined within any of the associations, they will also appear in the response.

If the employee identifier provided in the URL does not exist within the business, the request will return a 404 Not Found error, specifying Employee not found in the message.

If there are no service associations for the employee (neither active nor completed), the request will return an empty array [].

Effective availability

Within each availability interval, it is possible to have both availability ranges by day type and effective availability defined by shift patterns or assignment calendars. The field type indicates which availability is effective in each case: DAY_TYPE, SHIFT_PATTERN, or CALENDAR.

View example

[
    {
        "ownerProduct": "0001-G",
        "product": "0001-G",
        "from": "2021-06-25",
        "splitPresence": true,
        "unplannable": false,
        "roles": [],
        "disponibility": [
            {
                "from": "2025-11-02",
                "ranges": [
                    {
                        "dayType": "ALL",
                        "startMinuteDay": 0,
                        "duration": 1440
                    }
                ],
                "type": "SHIFT_PATTERN",
                "timeFramePatternId": "f314b8b2-2011-43af",
                "weekStart": 1,
                "blockedType": "NON_EXTENSIBLE_TIME"
            }
        ],
        "service": "0001",
        "person": {
            "name": "Sam",
            "surname": "Cole",
            "employeeId": "0002",
            "virtual": false
        }
    }
]

In this example, although the employee has default availability every day (ALL) from 00:00 to 00:00, their effective availability is defined by shift pattern (SHIFT_PATTERN), which causes the other fields related to this type of availability to also be returned: timeFramePatternId, weekStart and blockedType.

To check the details of the effective availability, it is recommended to use the following requests:

Useful links

What is a service association? And what is a cession?

What is employee availability?