Get effective availability by service

This endpoint allows to retrieve the effective availability of the employees of a service within a time period not exceeding 31 days.

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

If the data included in the request is correct —both the businessId and the serviceId— the response will contain the availability of all employees of the service, detailing the following information:

serviceId: external identifier of the service.
from: start date of the requested period.
to: end date of the requested period.
disponibilityIntervals: set of availability intervals defined within the requested time range.
- day: day of the availability.
- type: type of availability defined for this day. Possible values are DAY_TYPE (day type), SHIFT_PATTERN (shift patterns), AVAILABILITY_PATTERN (availability patterns) and CALENDAR (assignment calendar).
- personId: external identifier of the employee to whom the availability belongs.
- 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 of the request:

GET /api/v1/businesses/BUSINESSID/services/SERVICEID/effectiveDisponibilities?from=2025-05-01&to=2025-05-03

Response snippet:

{
    "serviceId": "SERVICEID",
    "from": "2025-05-01",
    "to": "2025-05-03",
    "disponibilityIntervals": [
        {
            "day": "2025-05-01",
            "type": "DAY_TYPE",
            "personId": "XX1",
            "free": false,
            "intervals": [
                {
                    "from": "2025-05-01T08:00:00.000Z",
                    "to": "2025-05-01T13:00:00.000Z"
                }
            ]
        },
        {
            "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": "DAY_TYPE",
            "personId": "XX1",
            "free": false,
            "intervals": [
                {
                    "from": "2025-05-03T08:00:00.000Z",
                    "to": "2025-05-03T13:00:00.000Z"
                }
            ]
        },
        {
            "day": "2025-05-01",
            "type": "CALENDAR",
            "personId": "XX2",
            "free": false,
            "intervals": [
                {
                    "from": "2025-05-01T07:00:00.000Z",
                    "to": "2025-05-01T08:00:00.000Z"
                },
                {
                    "from": "2025-05-01T13:00:00.000Z",
                    "to": "2025-05-01T18:00:00.000Z"
                }
            ]
        },
        {
            "day": "2025-05-02",
            "type": "CALENDAR",
            "personId": "XX2",
            "free": false,
            "intervals": [
                {
                    "from": "2025-05-02T07:00:00.000Z",
                    "to": "2025-05-02T08:00:00.000Z"
                },
                {
                    "from": "2025-05-02T13:00:00.000Z",
                    "to": "2025-05-02T18:00:00.000Z"
                }
            ]
        },
        {
            "day": "2025-05-03",
            "type": "CALENDAR",
            "personId": "XX2",
            "free": true,
            "intervals": []
        },
        {
            "day": "2025-05-01",
            "type": "AVAILABILITY_PATTERN",
            "personId": "XX3",
            "free": false,
            "intervals": [
                {
                    "from": "2025-05-01T16:00:00.000Z",
                    "to": "2025-05-01T22:00:00.000Z"
                }
            ]
        },
        {
            "day": "2025-05-02",
            "type": "AVAILABILITY_PATTERN",
            "personId": "XX3",
            "free": false,
            "intervals": [
                {
                    "from": "2025-05-02T16:00:00.000Z",
                    "to": "2025-05-02T22:00:00.000Z"
                }
            ]
        },
        {
            "day": "2025-05-03",
            "type": "AVAILABILITY_PATTERN",
            "personId": "XX3",
            "free": false,
            "intervals": [
                {
                    "from": "2025-05-03T16:00:00.000Z",
                    "to": "2025-05-03T22:00:00.000Z"
                }
            ]
        }
    ]
}

As shown in the example, the request will return the availability of each service employee for each day of the time range indicated in the URL.

Considerations

If an employee has multiple availability intervals defined within the specified range, the request will return the details for each of them.

If the service specified in the URL does not exist within the business, the request will return a 404 Not Found error indicating not exits.

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

If no availability intervals are defined for the service or for the requested date range, the disponibilityIntervals field will contain an empty array [].

Useful links

What is employee availability?