Announcements
Default Record Count Change
From November 2025, we are issuing a 3‑month notice for a change to the default number of records returned by our API endpoints. The changes come into effect from February 2026 onwards.
Instead of returning 250 records per endpoint which is the current default value, we are increasing the default page size with an optimised value. These endpoints also update in batches.
This table shows the changes for each endpoint and when you can expect them to take effect:
| Endpoint | Current Records Returned | New Records Returned | Change Date |
|---|---|---|---|
| /Employees | 250 | 1000 | Feb-26 |
| /Jobs | 250 | 2000 | March-26 |
| /Bankdetails | 250 | 5000 | March-26 |
| /EmergencyContacts | 250 | 6000 | April-26 |
| /Hierarchy | 250 | 10000 | April-26 |
| /AbsenceReason | 250 | 10000 | May-26 |
| /Absence | 250 | TBC | May-26 |
| /AbsenceDay | 250 | 10000 | May-26 |
| /Entitlement | 250 | TBC | June-26 |
| /Benefits | 250 | 1000 | June-26 |
| /WorkingPatterns | 250 | TBC | June-26 |
| /WorkingPatternsComponents | 250 | TBC | June-26 |
If we have not listed an endpoint in the table, this means the number of records will not be changing for that endpoint, and will remain at the default value of 250 records.
Why we are changing this
-
Limiting all endpoints to 250 causes a high volume of unnecessary requests for many customers. Endpoint‑specific defaults will reduce request volume and improve performance.
Timeline
-
Notice issued: November 2025
-
Changes take effect: February 2026
-
Rollout: each endpoint will be updated separately; we will announce each endpoint change in advance
Who is likely to be affected?
-
Any integration that relies on the implicit default page size of 250
-
Integrations that use OData's $skip without $top (for example, using only $skip to move through pages)
-
Integrations that assume a constant 250 record page across all endpoints
Impact and example
-
Current behaviour (example): GET https://api.iris.co.uk/hr/v2/Employees?$skip=250
-
Today this returns records 251–500 because the server defaults to returning 250 records.
-
-
After change (Employee endpoint default = 1000): GET https://api.iris.co.uk/hr/v2/Employees?$skip=250
-
This will return records 251–1250 (because default top is now 1000) and will therefore overlap with records 251–1000
-
-
To avoid overlap, explicitly set $top to the page size you expect. For example:
-
GET https://api.iris.co.uk/hr/v2/Employees?$top=250&$skip=250 — returns records 251–500 (consistent with previous paging of 250)
-
Recommended actions (what you should do)
-
Do not rely on an implicit default page size. Explicitly set $top in all requests where you depend on a specific page size.
-
Ensure your code always uses a stable ordering (for example, $orderby=EmployeeId or $orderby=LastModified) so paging is deterministic.
-
Review all integrations that use $skip and $top:
-
If you currently use $skip only, update to use $top as well. ( $skip should be a multiple of $top )
-
If you already set $top explicitly, you may not need to change anything (unless you want to adopt the new defaults).
-
-
Alternatively use @odata.nextLink that is returned in the response. Once there are no more pages, this node will not be present.
Test your changes before February 2026 and deploy updates in good time.
FAQs
Q: Will all endpoints have the same value?
A: No. Each endpoint will have its own optimised default value.
Q: Can I keep the old 250 behaviour?
A: Yes — explicitly set $top=250 in your requests to maintain the same page length.
Q: How can I avoid duplicate or missing records after the change?
A: Always set $top, use a stable $orderby and use $skip in multiples of $top (e.g. $skip=0, $skip=250, $skip=500 when $top=250).
Need help?
If you have questions on this change, email: HRAPI@iris.co.uk
Retirement of Cascade HR API - February 28th 2024
Version 1 (V1) of the Cascade HR API, officially became unsupported in July 2022, when we released Version 2 (V2). Most of you will already be using our V2 endpoints. However, we would like to give you advance notice that the following V1 endpoints will be retired in three months.
-
Employee/Jobs
-
Hierarchy
Our newer versions of these services include many additional features, enhancements, and improvements that we believe will benefit you greatly. We encourage you to use our v2 API services as soon as possible to take advantage of these benefits.
The final date of the v1 API's availability will be three months from now (February 28th 2024). At this point, the service will be turned off, and you will no longer be able to access data via it. Please make the switch over to the newer V2 by this time.
We apologise for any inconvenience this may cause, but believe that updating to our newer version will improve your experience.
Thank you for your attention and understanding. If you have any questions or concerns, please don't hesitate to contact us.