Get effective availability by employee

This endpoint allows to query the effective availability of an employee over a time period not exceeding 31 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 contain the employee’s availability, detailing the following information:

  • 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.

Below is an example request:

GET /api/v1/businesses/BUSINESSID/people/XX1/effectiveDisponibilities?from=2025-05-02&to=2025-05-05

Response:

[
    {
        "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": []
    }
]

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 the employee ID specified in the URL does not exist in the business, the request will return an error indicating Person not found for business.

If the time range specified in the URL exceeds 31 days, the request will return a 400 Bad Request error, with the message The maximum days to calculate must be 31 days.

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

Useful Links

What is employee availability?