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 32 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 be a 200 OK with the availability of all employees of the service.

Response example

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

Details

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.

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 no availability intervals are defined for the service or for the requested date range, the disponibilityIntervals field will contain an empty array [].

Error codes

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

Code Message Description

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.

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?