Calendar Events API

The full URL, including your unique endpoint ID, is provided to you when your access is set up. Treat it as sensitive.

Every request must include an Authorization header whose value is your API key exactly as issued.

The key is sent raw — do not prefix it with Bearer. The header name itself is case-insensitive (Authorization and authorization both work), but the key value must match exactly.

If an IP allow-list has been configured for your endpoint, requests must also originate from a registered public IP address. If no allow-list is configured, requests are accepted from any source presenting a valid key.

A request with a missing or incorrect API key, or from an unregistered IP address, returns no data.

This endpoint accepts GET requests. Parameters are supplied as query string parameters:

All three parameters are optional. A bare call with no parameters returns all events for the current calendar year.

Use the senseHrId values returned by the Employee Data API to reference employees consistently across both endpoints.

All events for the current calendar year (no parameters):

A specific date range:

One employee, first half of the year:

Several employees:

A successful request returns HTTP 200 with Content-Type: application/json. The body is an object with a single data property containing an array of event records:

If no events fall within the range, data is an empty array. The order of records is not guaranteed — sort client-side if order matters.

Fields shown as … | null are null when the underlying value is not held in Sense HR. Empty text values are normalised to null rather than returned as empty strings.

Public holidays are excluded from this endpoint. Sense HR records a separate public holiday event against every employee, which would otherwise dominate the response — a single bank holiday produces one record per person. Records with an event type of PUBLIC_HOLIDAY are therefore filtered out before the response is returned.

Treat this list as open. New event types may appear as Sense HR develops, so handle unrecognised values gracefully rather than assuming the set above is exhaustive.

Pending events are included in the response. If you only want confirmed absence, filter to APPROVED and AUTO_APPROVED client-side.

plannerEventId identifies an event group, not a single record, and the same value can appear on multiple records where one event spans several employees. Do not use it alone as a primary key.

To identify a record uniquely, use the combination of plannerEventId and senseHrId. If you are caching records or performing upserts, key on both fields.

duration is returned exactly as recorded in Sense HR and should be interpreted alongside durationUnit. Be aware that the two are not always consistent: values recorded against DAY do not reliably represent a number of days, and outlying values do occur.

Do not use duration to calculate leave entitlement or remaining balance. Use it as an indicative figure only, and take entitlement figures from Sense HR directly.

Note also that the default date range is a calendar year. If your leave year runs on different dates, a default request spans two leave years — another reason not to aggregate duration across a response.

The sicknessReason field contains health information about identifiable individuals. Under UK GDPR this is special category personal data and attracts additional protection beyond ordinary personal data.

Anyone holding your API key can retrieve it. Before consuming this field, satisfy yourself that:

If you do not need sickness reasons, discard the field on receipt rather than storing it. If you would prefer it withheld from your endpoint entirely, contact us and we can arrange that.

I get fewer records than expected, or only one or two. Check the dates you sent. If startDate or endDate was missing or malformed, the default range applied silently — no error is returned for an unparseable date. A value such as 01/12/2025 is not valid and will be ignored. Confirm the range by sending both parameters explicitly in the format YYYY-MM-DD.

I asked for one employee but got everyone. The senseHrId value was not in a valid format, so the filter was discarded. Check the ID against the value returned by the Employee Data API.

Bank holidays and weekends appear inside a multi-day event. startDate and endDate describe the span the event was booked across. Non-working days within that span are not broken out.

No response, or an error rather than data. Confirm the Authorization header is present and contains the key exactly as issued, with no Bearer prefix. If an IP allow-list is configured, confirm your request originates from a registered address.

Employee Data API — returns employee records including names, roles, departments, and line managers. The senseHrId field is shared between both endpoints, so records can be joined directly.