Get effective availability by employee

This endpoint allows to query the effective availability of an employee over a time period not exceeding 32 days.

GET /api/v1/businesses/{businessId}/people/{employeeId}/effectiveDisponibilities?from={yyyy-MM-dd}&to={yyyy-MM-dd}

If the data included in the request is correct —both businessId and employeeId—, the response will be a 200 OK with the employee’s availability.

Response example

[
    {
        "day": "2025-05-02",
        "type": "DAY_TYPE",
        "personId": "XX1",
        "free": false,
        "intervals": [
            {
                "from": "2025-05-02T08:00:00.000Z",
                "to": "2025-05-02T13:00:00.000Z"
            }
        ]
    },
    {
        "day": "2025-05-03",
        "type": "AVAILABILITY_PATTERN",
        "personId": "XX1",
        "free": false,
        "intervals": [
            {
                "from": "2025-05-03T16:00:00.000Z",
                "to": "2025-05-03T22:00:00.000Z"
            }
        ]
    },
    {
        "day": "2025-05-04",
        "type": "AVAILABILITY_PATTERN",
        "personId": "XX1",
        "free": false,
        "intervals": [
            {
                "from": "2025-05-04T16:00:00.000Z",
                "to": "2025-05-04T22:00:00.000Z"
            }
        ]
    },
    {
        "day": "2025-05-05",
        "type": "SHIFT_PATTERN",
        "personId": "XX1",
        "free": true,
        "intervals": []
    }
]
Details

  • day: day of availability.

  • type: type of availability defined for this day. Possible values are DAY_TYPE (day type), SHIFT_PATTERN (shift pattern), AVAILABILITY_PATTERN (availability pattern), and CALENDAR (assignment calendar).

  • personId: external identifier of the employee whose availability is being returned.

  • free: whether it is a free day (true) or not (false).

  • intervals: availability intervals.

    • from: start date and time of the availability.

    • to: end date and time of the availability.

As shown in the example, the request returns the effective availability of the employee for each day in the period specified in the URL.

Considerations

If there are no availability intervals defined for the employee or for the requested date range, the response will contain an empty array [].

Error codes

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

Code Message Description

400 Bad Request

From-date must be before to-date

The date specified in to is earlier than the one specified in from. It is recommended to check the order of the two dates in the URL. This text travels in the cause field; the message field repeats it followed by the list of error parameters.

Useful links

What is employee availability?