Calendar Events API | Sense Help Centre

Base URL

https://api.automate.sensewp.com/package/http/endpoint/{your-endpoint-id}

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

Authentication

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

Authorization: your-api-key-here

The key is sent raw, so 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.

Making a request

This endpoint accepts POST requests. Parameters are supplied as a JSON object in the request body, and the request must include a Content-Type: application/json header.

POST /{your-endpoint-id} Content-Type: application/json  {"startDate":"2026-01-01","endDate":"2026-06-30"}

Parameters passed in the query string are ignored. They are silently discarded and the default range applies. A GET request returns 405 Method Not Allowed.

All three parameters are optional. A request with no body, or an empty body, returns all events for the current calendar year.

Parameters

Parameters are supplied as fields in the JSON request body.

Parameter	Type	Description
`startDate`	string	Start of the date range, as `YYYY-MM-DD`. Events on this date are included.
`endDate`	string	End of the date range, as `YYYY-MM-DD`. Events on this date are included.
`senseHrId`	string \| array	Restrict results to specific employees. Omit for all employees.

startDate and endDate behaviour

Both must be formatted YYYY-MM-DD (for example 2026-03-31). Other formats, including 31/03/2026 and 2026-3-31, are not accepted.

If startDate is omitted, empty, or not a valid date, it defaults to 1 January of the current year.

If endDate is omitted, empty, or not a valid date, it defaults to 31 December of startDate's year. Note this follows the year of startDate, not the current year: a request for startDate of 2024-06-15 alone returns 2024-06-15 to 2024-12-31.

If endDate is earlier than startDate, it is adjusted to equal startDate, returning a single day rather than an inverted range.

senseHrId behaviour

If omitted, events for all employees are returned.

If supplied, only events for those employees are returned. IDs must be valid GUIDs. Two formats are accepted:

a single ID as a string: "senseHrId": "6e6d2b45-5701-47e3-b64d-525b307dd8f1"
an array of IDs: "senseHrId": ["6e6d2b45-5701-47e3-b64d-525b307dd8f1", "c9d33249-581e-4be9-9a77-74be056e87cd"]

IDs that are not in a valid format are ignored. If none of the supplied IDs are valid, the filter is treated as empty and events for all employees are returned.

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

Example requests

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

bash

curl -X POST "https://api.automate.sensewp.com/package/http/endpoint/{your-endpoint-id}" \   -H "Authorization: your-api-key-here"

A specific date range:

bash

curl -X POST "https://api.automate.sensewp.com/package/http/endpoint/{your-endpoint-id}" \   -H "Authorization: your-api-key-here" \   -H "Content-Type: application/json" \   -d '{"startDate":"2025-12-01","endDate":"2026-12-01"}'

One employee, first half of the year:

bash

curl -X POST "https://api.automate.sensewp.com/package/http/endpoint/{your-endpoint-id}" \   -H "Authorization: your-api-key-here" \   -H "Content-Type: application/json" \   -d '{"startDate":"2026-01-01","endDate":"2026-06-30","senseHrId":"6e6d2b45-5701-47e3-b64d-525b307dd8f1"}'

Several employees:

bash

curl -X POST "https://api.automate.sensewp.com/package/http/endpoint/{your-endpoint-id}" \   -H "Authorization: your-api-key-here" \   -H "Content-Type: application/json" \   -d '{"senseHrId":["6e6d2b45-5701-47e3-b64d-525b307dd8f1","c9d33249-581e-4be9-9a77-74be056e87cd"]}'

Response

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:

json

{ "data": [ { "plannerEventId": "…", "senseHrId": "…", "...": "…" } ] }

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

Event fields

Field	Type	Description
`plannerEventId`	string	Identifier for the event in Sense HR. Not unique on its own. See Identifying a record.
`senseHrId`	string	Unique, stable Sense HR identifier for the employee the event belongs to. Matches the `senseHrId` returned by the Employee Data API.
`firstName`	string \| null	Employee's first name.
`lastName`	string \| null	Employee's last name. `null` where the employee has only a single recorded name.
`eventTitle`	string \| null	The name of the event as configured in Sense HR, for example Holiday, Sickness, Birthday Leave, TOIL, Overtime, Compassionate Leave, Working from home. This list is not fixed and reflects your own configuration.
`eventType`	string	The category of event. See Event types.
`status`	string	Approval state. See Statuses.
`startDate`	string \| null	First day of the event, ISO 8601 (UTC), e.g. `2026-05-27T00:00:00.000Z`.
`endDate`	string \| null	Last day of the event, ISO 8601 (UTC). Equal to `startDate` for single-day events.
`startTime`	string \| null	Start time as `HH:MM` (24-hour) for part-day events. `null` where the event is not time-bounded.
`endTime`	string \| null	End time as `HH:MM` (24-hour). `null` where the event is not time-bounded.
`duration`	number \| null	Length of the event, interpreted according to `durationUnit`. See the caution under Working with duration.
`durationUnit`	string \| null	`DAY` or `HOUR`, the unit `duration` is recorded in. `null` where no unit is held.
`sicknessReason`	string \| null	Recorded reason for a sickness absence, e.g. Covid. `null` for all non-sickness events.
`shiftPart`	string \| null	`FULL_DAY` where the event covers a whole shift. `null` where not applicable.
`notes`	string \| null	Free-text note attached to the event. `null` where no note was entered.

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.

Event types

eventType	Meaning
`TIME_OFF`	Absence deducted from or associated with leave, such as holiday, birthday leave, and TOIL.
`SICKNESS`	Sickness absence. May carry a `sicknessReason`.
`WORKING`	The employee is working, but the day is marked, such as overtime or working from home.

Public holidays are excluded from this endpoint. Sense HR records a separate public holiday event against every employee, which would otherwise dominate the response, since 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.

Statuses

status	Meaning
`APPROVED`	Approved by a manager.
`AUTO_APPROVED`	Approved automatically, without requiring manager action.
`PENDING`	Requested but not yet approved.

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

Example response

json

{   "data": [     {       "plannerEventId": "e6e2f06a-4bd7-4d29-a5b3-355024492f5d",       "senseHrId": "c9d33249-581e-4be9-9a77-74be056e87cd",       "firstName": "Stew",       "lastName": "Welsh",       "eventTitle": "TOIL",       "eventType": "TIME_OFF",       "status": "APPROVED",       "startDate": "2026-05-27T00:00:00.000Z",       "endDate": "2026-05-27T00:00:00.000Z",       "startTime": "05:21",       "endTime": "12:21",       "duration": 7,       "durationUnit": "HOUR",       "sicknessReason": null,       "shiftPart": null,       "notes": null     },     {       "plannerEventId": "3ce83b77-e76a-4ee6-b283-c896bca6c94f",       "senseHrId": "3a50f03d-8a65-47ff-acf2-3abb9f7d4931",       "firstName": "Alex",       "lastName": "Gallagher",       "eventTitle": "Holiday",       "eventType": "TIME_OFF",       "status": "AUTO_APPROVED",       "startDate": "2026-07-15T00:00:00.000Z",       "endDate": "2026-07-17T00:00:00.000Z",       "startTime": null,       "endTime": null,       "duration": 3,       "durationUnit": "DAY",       "sicknessReason": null,       "shiftPart": "FULL_DAY",       "notes": null     }   ] }

Notes and guidance

Identifying a record

plannerEventId identifies an event group rather than 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.

Working with duration

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, which is another reason not to aggregate duration across a response.

Sensitive data

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:

you have a lawful basis and an Article 9 condition for processing it;
the systems you send it to are appropriate for special category data;
access is limited to those who need it, and it is not exposed in dashboards, logs, or reports more widely than intended.

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.

Troubleshooting

My date range or employee filter is ignored. Parameters must be sent as a JSON body with a Content-Type: application/json header. Query string parameters are silently discarded and the default range applies.

I get a 405 Method Not Allowed. The endpoint accepts POST only. Use -X POST in curl.

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, since 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.

Related endpoints

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.