Skip to main content

Entitlements API

This endpoint returns event entitlements from Sense HR: for holiday, TOIL and any other planner event type with an allowance, each employee's total, taken, booked and remaining balance for every entitlement period.

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 carry an Authorization header whose value is your API key, exactly as issued:

Authorization: your-api-key-here
  • Send the key on its own. Do not prefix it with Bearer.

  • Send the same header on the retrieval request (Step 2) as well as the submission.

  • If an IP allow-list is configured for your endpoint, requests must come from one of the registered public IP addresses. If none is configured, any source presenting a valid key is accepted.

Getting your API key. When access is set up, two emails go to the nominated address: a secure link to a form that shows the key, then a PIN that opens it. The form stays available for 24 hours, or until Close is pressed. After that the key cannot be shown again, and a new key (with a new endpoint URL) has to be issued.

A missing or wrong key, or a request from an unregistered IP, returns no data. These checks happen after submission, so the submission still answers 202; the retrieval URL then answers 404.

Making a request

Gathering entitlements for a whole company can take longer than a single HTTP request should wait, so a request is made in two steps.

Step

Method

URL

Returns

1. Submit

POST

Your endpoint URL

202 Accepted and a Location header

2. Retrieve

GET

The URL from Location

202 while pending, 200 with data when ready

The methods are not interchangeable. The endpoint URL accepts POST only (anything else returns 405), and the retrieval URL accepts GET only.

Step 1 — Submit the request

POST to your endpoint URL with the parameters as a JSON object in the request body, and Content-Type: application/json. An empty body, or {}, is valid and returns all employees. The body may be up to 1 MB.

POST /package/http/endpoint/{your-endpoint-id} Authorization: your-api-key-here Content-Type: application/json X-Request-Id: 4f1c2a8e-6b0d-4c3e-9a57-2d8e1f0b7c64  { "senseHrId": ["ead62e28-41a3-4bd5-b15f-05fc60b8ca36"] }

The response is 202 Accepted with no body. Its Location header is the path to retrieve the result from. Prefix it with the API host; do not build it yourself or assume the length or characters of the token in it.

  • 202 is not a redirect. Clients will not follow Location automatically, and curl -L will not either. Make the second request yourself.

  • Use X-Request-Id to retry safely. Send a unique value, such as a GUID, with each new request. Resubmitting with the same X-Request-Id and the same body returns the original request instead of starting a new one; the same ID with a different body is rejected with 422. Without the header, every POST starts a new request.

Step 2 — Retrieve the result

GET the Location URL. Do not POST to it.

Status

Meaning

What to do

202

Not ready yet

Wait, then request the same URL again

200

Ready

Stop polling and process the body

404

Rejected: missing or wrong API key, or IP not allowed

Stop; see Authentication

410

Result expired or no longer available

Stop; submit a new request

500

The request failed before a result was produced

Stop; submit again, and contact us if it persists

A result can be retrieved for 1 hour after submission. Treat any status other than 202 or 200 as final.

Recommended polling behaviour

  • Wait 1–2 seconds before the first attempt.

  • Retry every 2–5 seconds.

  • Give up after an overall timeout; 60 seconds is a sensible starting point.

  • Do not poll in a tight loop; it does not make results arrive sooner.

A handful of employees is usually ready almost at once. Every employee in a large organisation takes longer.

Parameters

Parameters go in the JSON body of the Step 1 POST. They are not read from the query string, and the retrieval GET takes none: it returns what the submission asked for. All parameters are optional; a bare submission returns every employee's entitlements.

Field

Type

Description

senseHrId

array of strings, or one comma-separated string

Employees to return. Omit for all employees.

eventTitle

string, up to 100 characters

Only this event type, by its name in Sense HR, e.g. Holiday.

plannerEventTypeId

string (GUID)

Only this event type, by its ID (the eventTypeId in a response).

queryCurrentYearOnly

boolean

true returns only the current entitlement period.

date

string, YYYY-MM-DD

Entitlements as at this date.

durationUnit

DAY or HOUR

Only entitlements recorded in this unit. Not case-sensitive.

Fields not in this table are ignored. Where a single value is expected and an array is sent, the first value is used.

senseHrId behaviour

  • Omitted, empty or blank: all employees.

  • Accepted forms: an array, ["ead62e28-41a3-4bd5-b15f-05fc60b8ca36", "c262cb12-ab5e-45a7-b785-b4573a450096"], or a comma-separated string, "ead62e28-41a3-4bd5-b15f-05fc60b8ca36,c262cb12-ab5e-45a7-b785-b4573a450096".

  • IDs are not case-sensitive, and duplicates are removed.

  • An ID that is not a valid GUID rejects the whole request with SENSE_HR_ID_INVALID. It is never dropped silently and never widens the request to all employees.

  • A valid ID that Sense HR holds no entitlements for is listed in meta.senseHrIdsWithoutData (see Response).

Use the senseHrId values from the Employee Core Data API, so IDs match across endpoints.

Filter behaviour

  • Filters are applied by Sense HR and can be combined, with each other and with senseHrId.

  • A filter that is supplied is honoured or rejected, never ignored: an unusable value returns an error (see Codes).

  • queryCurrentYearOnly accepts true / false, or the strings "true" / "false".

  • date must be a real calendar date in YYYY-MM-DD form; 01/03/2027, 2027-3-1 and 2026-02-30 are rejected.

  • Every filter you supplied is echoed back in meta.filters, so you can confirm what was applied.

Example requests

Step 1 — submit, all employees (-i prints the response headers):

curl -i -X POST "https://api.automate.sensewp.com/package/http/endpoint/your-endpoint-id" \   -H "Authorization: your-api-key-here" \   -H "Content-Type: application/json" \   -H "X-Request-Id: $(uuidgen)" \   -d '{}'
HTTP/1.1 202 Accepted Location: /package/http/endpoint/requests/{token}

Step 2 — retrieve. Repeat until the status is 200, not 202. GET is curl's default, so no -X is needed.

curl -i "https://api.automate.sensewp.com/package/http/endpoint/requests/{token}" \   -H "Authorization: your-api-key-here"

Filtered submission: current-year holiday balances for two employees, in days.

curl -i -X POST "https://api.automate.sensewp.com/package/http/endpoint/your-endpoint-id" \   -H "Authorization: your-api-key-here" \   -H "Content-Type: application/json" \   -H "X-Request-Id: $(uuidgen)" \   -d '{     "senseHrId": ["ead62e28-41a3-4bd5-b15f-05fc60b8ca36", "c262cb12-ab5e-45a7-b785-b4573a450096"],     "eventTitle": "Holiday",     "queryCurrentYearOnly": true,     "durationUnit": "DAY"   }'

Do not add -L to the submission: 202 is not a redirect, and following it can turn your POST into a GET.

Submit and poll — shell

BASE="https://api.automate.sensewp.com" ENDPOINT="$BASE/package/http/endpoint/your-endpoint-id" KEY="your-api-key-here" BODY='{"senseHrId": ["ead62e28-41a3-4bd5-b15f-05fc60b8ca36"], "queryCurrentYearOnly": true}'  # Step 1: submit, keeping only the Location header LOCATION=$(curl -s -D - -o /dev/null -X POST "$ENDPOINT" \   -H "Authorization: $KEY" \   -H "Content-Type: application/json" \   -H "X-Request-Id: $(uuidgen)" \   -d "$BODY" | awk 'tolower($1) == "location:" { print $2 }' | tr -d '\r')  if [ -z "$LOCATION" ]; then echo "No Location header returned" >&2; exit 1; fi case "$LOCATION" in http*) URL="$LOCATION" ;; *) URL="$BASE$LOCATION" ;; esac  # Step 2: poll until the result is ready sleep 2 for i in $(seq 1 20); do   STATUS=$(curl -s -o result.json -w '%{http_code}' "$URL" -H "Authorization: $KEY")   if [ "$STATUS" = "200" ]; then echo "Ready: result.json"; exit 0; fi   if [ "$STATUS" != "202" ]; then echo "Stopped: HTTP $STATUS" >&2; exit 1; fi   sleep 3 done echo "Timed out waiting for the result" >&2; exit 1

Submit and poll — JavaScript

const BASE = "https://api.automate.sensewp.com"; const ENDPOINT = `${BASE}/package/http/endpoint/your-endpoint-id`; const KEY = "your-api-key-here";  const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));  async function getEntitlements(params = {}, { timeoutMs = 60000, intervalMs = 3000 } = {}) {   const auth = { Authorization: KEY };    // Step 1: submit   const submit = await fetch(ENDPOINT, {     method: "POST",     headers: { ...auth, "Content-Type": "application/json", "X-Request-Id": crypto.randomUUID() },     body: JSON.stringify(params),     redirect: "manual",   });   const location = submit.headers.get("Location");   if (submit.status !== 202 || !location) throw new Error(`Submission failed: HTTP ${submit.status}`);   const resultUrl = new URL(location, BASE);    // Step 2: poll until ready   const deadline = Date.now() + timeoutMs;   await sleep(1500);   while (Date.now() < deadline) {     const res = await fetch(resultUrl, { headers: auth });     if (res.status === 200) {       const body = await res.json();       if (body.error) throw new Error(`${body.error.code}: ${body.error.message}`);       return body; // { meta, data }     }     if (res.status !== 202) throw new Error(`Retrieval failed: HTTP ${res.status}`);     await sleep(intervalMs);   }   throw new Error("Timed out waiting for the result"); }  // Current-year holiday balances for two employees const { meta, data } = await getEntitlements({   senseHrId: ["ead62e28-41a3-4bd5-b15f-05fc60b8ca36", "c262cb12-ab5e-45a7-b785-b4573a450096"],   eventTitle: "Holiday",   queryCurrentYearOnly: true, });

Response

When ready, the retrieval URL returns 200 with Content-Type: application/json and two top-level keys, meta and data.

meta field

Type

Description

senseHrIds

array

The employees requested. An empty array means all employees.

filters

object

The filters applied, under the names you sent, with values normalised (for example "day" becomes "DAY"). {} when none.

peopleRequested

number | null

How many employees you named; null when all employees were requested.

peopleReturned

number

How many employees have at least one record in data.

senseHrIdsWithoutData

array

Requested employees with no entitlements in the result; always empty when all employees were requested.

recordCount

number

Number of records in data.

generatedAt

string

When the response was produced, ISO 8601 UTC.

One record is one employee, for one event type, for one entitlement period. An employee with Holiday and TOIL entitlements over two periods has four records. If nothing matches, data is an empty array. Record order is not guaranteed.

Entitlement fields

Field

Type

Description

senseHrId

string

Stable Sense HR identifier; matches the Attendance, Calendar Events and Employee Core Data APIs.

eventTypeId

string | null

Identifier of the event type in Sense HR.

eventTitle

string | null

Name of the event type, e.g. Holiday, TOIL. The list is configured per organisation, not fixed.

entitlementPeriodType

string | null

How the entitlement period runs, e.g. YEARLY. Treat as open and handle unknown values.

year

string | null

Label of the entitlement period, e.g. 2026.

startDate

string | null

First day of the entitlement period, YYYY-MM-DD.

endDate

string | null

Last day of the entitlement period, YYYY-MM-DD.

isCurrentYear

boolean | null

true for the period that covers today.

durationUnit

DAY | HOUR | null

Unit for every amount in this record.

total

number | null

Total entitlement for the period.

taken

number | null

Entitlement already taken.

bookedDuration

number | null

Entitlement booked.

remaining

number | null

Entitlement still available.

carryOver

number | null

Entitlement carried over from the previous period.

lengthOfService

number | null

Extra entitlement awarded for length of service.

publicHolidayDuration

number | null

Public holiday time accounted for in the entitlement.

lost

number | null

Entitlement lost, for example not carried over.

Fields shown as "… | null" are null where Sense HR holds no value. Empty text is returned as null, never as an empty string.

Example response

For {"senseHrId": ["ead62e28-41a3-4bd5-b15f-05fc60b8ca36", "c262cb12-ab5e-45a7-b785-b4573a450096"], "queryCurrentYearOnly": true}:

{   "meta": {     "senseHrIds": ["ead62e28-41a3-4bd5-b15f-05fc60b8ca36", "c262cb12-ab5e-45a7-b785-b4573a450096"],     "filters": { "queryCurrentYearOnly": true },     "peopleRequested": 2,     "peopleReturned": 2,     "senseHrIdsWithoutData": [],     "recordCount": 3,     "generatedAt": "2026-11-16T10:42:07.118Z"   },   "data": [     {       "senseHrId": "ead62e28-41a3-4bd5-b15f-05fc60b8ca36",       "eventTypeId": "3e588031-82bf-48be-8d6b-73043fcfbacd",       "eventTitle": "Holiday",       "entitlementPeriodType": "YEARLY",       "year": "2026",       "startDate": "2026-01-01",       "endDate": "2026-12-31",       "isCurrentYear": true,       "durationUnit": "DAY",       "total": 15.07,       "taken": 0,       "bookedDuration": 0,       "remaining": 15.07,       "carryOver": 0,       "lengthOfService": 0,       "publicHolidayDuration": 0,       "lost": 0     },     {       "senseHrId": "c262cb12-ab5e-45a7-b785-b4573a450096",       "eventTypeId": "3e588031-82bf-48be-8d6b-73043fcfbacd",       "eventTitle": "Holiday",       "entitlementPeriodType": "YEARLY",       "year": "2026",       "startDate": "2026-01-01",       "endDate": "2026-12-31",       "isCurrentYear": true,       "durationUnit": "DAY",       "total": 2.9,       "taken": 1,       "bookedDuration": 1,       "remaining": 1.9,       "carryOver": 0,       "lengthOfService": 0,       "publicHolidayDuration": 0,       "lost": 0     },     {       "senseHrId": "c262cb12-ab5e-45a7-b785-b4573a450096",       "eventTypeId": "b4d10caf-0615-4eb2-9364-de08ec95f8bf",       "eventTitle": "TOIL",       "entitlementPeriodType": "YEARLY",       "year": "2026",       "startDate": "2026-01-01",       "endDate": "2026-12-31",       "isCurrentYear": true,       "durationUnit": "DAY",       "total": 0,       "taken": 0,       "bookedDuration": 0,       "remaining": 0,       "carryOver": 0,       "lengthOfService": 0,       "publicHolidayDuration": 0,       "lost": 0     }   ] }

Error responses

A request that cannot be served still returns HTTP 200 from the retrieval URL, with an error object in place of meta and data. Always check for error before reading data.

Field

Description

code

Stable identifier. Branch on this.

message

Human-readable explanation, safe to log. Where useful it echoes the value that failed, shortened if long.

details

Only on HR_REQUEST_FAILED: the messages Sense HR returned.

{   "error": {     "code": "DATE_INVALID",     "message": "date must be a real calendar date in YYYY-MM-DD format. Received: \"2026-02-30\"."   } }

Codes

Code

Meaning

Fix

SENSE_HR_ID_INVALID

A senseHrId value is not a valid GUID.

Correct or remove that ID; the message shows it.

EVENT_TITLE_INVALID

eventTitle is over 100 characters.

Send the event type's name as shown in Sense HR.

PLANNER_EVENT_TYPE_ID_INVALID

plannerEventTypeId is not a valid GUID.

Use an eventTypeId from a previous response.

QUERY_CURRENT_YEAR_ONLY_INVALID

queryCurrentYearOnly is not true or false.

Send a boolean.

DATE_INVALID

date is not a real calendar date in YYYY-MM-DD form.

Reformat it. 2026-02-30 is well formed but not real, so it is rejected.

DURATION_UNIT_INVALID

durationUnit is not DAY or HOUR.

Send DAY or HOUR.

HR_REQUEST_FAILED

Sense HR could not answer the request.

Check details; retry later, and contact us if it persists.

Validation happens after submission. The POST returns 202 before parameters are checked, so a rejection arrives on the retrieval GET. The list of codes may grow: branch on the codes you know and fall back to showing message.

Notes and guidance

Identifying a record

There is no single-field record ID. A record is unique by senseHrId + eventTypeId + startDate: one employee, one event type, one entitlement period.

Days and hours

Every amount in a record is in that record's durationUnit. One employee can have a Holiday entitlement in days and a TOIL entitlement in hours, so never add amounts across records without checking durationUnit. To keep a whole response in one unit, send durationUnit.

Current and upcoming periods

A response can include the next entitlement period as well as the current one, for example 2027 while it is still 2026. Use isCurrentYear to pick out the current period, or send queryCurrentYearOnly: true to receive only that.

Confirming what you got

Check meta.filters and meta.senseHrIds against what you sent. meta.senseHrIdsWithoutData lists employees you asked for who have no entitlements in the result, for example a new starter with no allowance yet or an ID from another organisation.

One request for many employees

Request all the employees you need in one submission rather than one request per employee. If you do make several requests, run them one after another, not in parallel.

Balances are a snapshot

Figures are as they stood in Sense HR at meta.generatedAt. Bookings, approvals and adjustments made afterwards are not reflected until you request again. Sense HR remains the system of record.

Personal data

Entitlement balances are personal data, and anyone holding the API key can retrieve them for every employee. Before use, check that:

  • you have a lawful basis for the purpose, and employees have been told;

  • the data is used only for that purpose;

  • access to the key and to the stored results is limited to those who need it;

  • results are kept no longer than needed.

Troubleshooting

Symptom

Cause and fix

Got 202 and no data

Expected on submission. GET the Location URL for the result.

The submission returned no Location

The request was not a POST. Only POST submits; anything else returns 405.

Keep getting 202

Keep polling. If it does not resolve after about a minute, check the URL is exactly as returned (not cut short or re-encoded).

Retrieval returns 404

Missing or wrong Authorization header, a Bearer prefix, or a request from an IP that is not on the allow-list. Fix it and submit again.

Retrieval returns 410

The result is more than an hour old or no longer available. Submit a new request.

Retrieval returns 500

The request failed before a result was produced. Submit again; contact us if it persists.

Submission returns 422

An X-Request-Id was reused with a different body. Use a new ID for each new request.

The client followed Location and got nothing

202 is not a redirect. Turn off automatic redirect following.

Every employee came back when I asked for a few

senseHrId was missing, misspelt (it is case-sensitive: senseHrId) or sent in the query string. Send it in the JSON body.

A filter seems to be ignored

Filters are read from the JSON body only, by the exact names in Parameters. Check meta.filters for what was applied.

200 but no data

The response is an error. Read error.code and error.message.

An employee I asked for is missing

Sense HR holds no entitlements for them. They are listed in meta.senseHrIdsWithoutData.

Totals look wrong when added up

Records may be in different units. Group by durationUnit first.

Related endpoints

Endpoint

Use it for

The planner events behind these balances: one record per event, with approval status and duration.

Day-by-day attendance: working pattern, clock-ins, breaks and events on each day.

Employee records: names, roles, departments and line managers.

senseHrId is the same across all of these endpoints, so records can be joined. Use the Employee Core Data API to add names to entitlement records.

Did this answer your question?