Employee calendar

We are pleased to announce the availability of the Employee Calendar API service.

It allows you to access an employee’s calendar over a given date range. It returns a generated calendar that can include working patterns, working pattern overrides, public holidays, and absences.

Features

  • Get a single employee’s generated calendar between a specified start date and end date. Max span 366 days

  • Control what is included via query parameters:

    • publicHolidays. Include Public Holidays in generated employee calendar - default: included

    • workingPatterns. Include Employee's Working Pattern in generated employee calendar - default: included

    • workingPatternOverrides. Include Employee's Working Pattern Overrides in generated employee calendar - default: included

    • absences . Include Employee's Absences in generated employee calendar - default: included

    • ignoreShowOnCalendar . Default: false — respects ShowOnCalendar property from the /attendance/absencereasons endpoint

  • Response includes a Days array with, per day:

    • Date, duration (days/minutes), working start/end times, day part (AM/PM/AllDay/None)

    • Public holiday ID and Friendly name

    • Working pattern and Working pattern overrides ID & Friendly name

    • Absence days with absence reason and duration

The Days array may contain multiple entries for a single day because it supports separate AM and PM events and allows for overlapping events.

  • Informational messages

    • While returning the calendar for an employee, there is an additional node called Messages. These Messages describe what data was included or any issues found when building the calendar

Use cases

  • Rostering and scheduling

    • Show an employee’s working days and overrides over a period

  • Leave and absence

    • View which days have absences and whether they are AM/PM/full day.

  • Public holidays

    • Identify public holidays and their descriptions

  • Reporting

    • Derive worked days or absence days

  • Integrations

    • Sync calendar data into HR, payroll, or productivity tools

Example requests

You can query the employee calendar with or without query parameters.

Basic request

https://api.iris.co.uk/hr/v2/calendar/employees?$startDate=2025-01-01&endDate=2025-12-31

When making this request, it will return all records (Bank Holidays, Employee's Working Pattern, Employee's Working Pattern Overrides and Employee's Absences).

Advanced request

https://api.iris.co.uk/hr/v2/calendar/employees?$startDate=2025-01
-01&endDate=2025131&publicHolidays=true&workingPatterns=true&workingPattern
Overrides=true&absences=true&ignoreShowOnCalendar=false

When making this request, you can control what returns if you don't want to use the default data. By changing the values of each query parameter, you get a more customised response with only the data you want.

Future Changes

Currently, when the calendar returns absence information, it displays an absence reason known as a Type in IRIS Cascade. We understand that you may want this information to be private, so we have decided in a future release to switch the absence reason to be the Category instead. This will align the calendar with IRIS Cascade's Planner and offer better privacy for your employees.