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 |
| Your endpoint URL |
|
2. Retrieve |
| The URL from |
|
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.
202is not a redirect. Clients will not followLocationautomatically, andcurl -Lwill not either. Make the second request yourself.Use
X-Request-Idto retry safely. Send a unique value, such as a GUID, with each new request. Resubmitting with the sameX-Request-Idand the same body returns the original request instead of starting a new one; the same ID with a different body is rejected with422. Without the header, everyPOSTstarts a new request.
Step 2 — Retrieve the result
GET the Location URL. Do not POST to it.
Status | Meaning | What to do |
| Not ready yet | Wait, then request the same URL again |
| Ready | Stop polling and process the body |
| Rejected: missing or wrong API key, or IP not allowed | Stop; see Authentication |
| Result expired or no longer available | Stop; submit a new request |
| 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 |
| array of strings, or one comma-separated string | Employees to return. Omit for all employees. |
| string, up to 100 characters | Only this event type, by its name in Sense HR, e.g. |
| string (GUID) | Only this event type, by its ID (the |
| boolean |
|
| string, | Entitlements as at this date. |
|
| 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).
queryCurrentYearOnlyacceptstrue/false, or the strings"true"/"false".datemust be a real calendar date inYYYY-MM-DDform;01/03/2027,2027-3-1and2026-02-30are 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 1Submit 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.
| Type | Description |
| array | The employees requested. An empty array means all employees. |
| object | The filters applied, under the names you sent, with values normalised (for example "day" becomes "DAY"). |
| number | null | How many employees you named; |
| number | How many employees have at least one record in |
| array | Requested employees with no entitlements in the result; always empty when all employees were requested. |
| number | Number of records in |
| 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 |
| string | Stable Sense HR identifier; matches the Attendance, Calendar Events and Employee Core Data APIs. |
| string | null | Identifier of the event type in Sense HR. |
| string | null | Name of the event type, e.g. |
| string | null | How the entitlement period runs, e.g. |
| string | null | Label of the entitlement period, e.g. |
| string | null | First day of the entitlement period, |
| string | null | Last day of the entitlement period, |
| boolean | null |
|
|
| Unit for every amount in this record. |
| number | null | Total entitlement for the period. |
| number | null | Entitlement already taken. |
| number | null | Entitlement booked. |
| number | null | Entitlement still available. |
| number | null | Entitlement carried over from the previous period. |
| number | null | Extra entitlement awarded for length of service. |
| number | null | Public holiday time accounted for in the entitlement. |
| 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 |
| Stable identifier. Branch on this. |
| Human-readable explanation, safe to log. Where useful it echoes the value that failed, shortened if long. |
| Only on |
{ "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 |
| A | Correct or remove that ID; the message shows it. |
|
| Send the event type's name as shown in Sense HR. |
|
| Use an |
|
| Send a boolean. |
|
| Reformat it. |
|
| Send |
| Sense HR could not answer the request. | Check |
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 | Expected on submission. |
The submission returned no | The request was not a |
Keep getting | 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 | Missing or wrong |
Retrieval returns | The result is more than an hour old or no longer available. Submit a new request. |
Retrieval returns | The request failed before a result was produced. Submit again; contact us if it persists. |
Submission returns | An |
The client followed |
|
Every employee came back when I asked for a few |
|
A filter seems to be ignored | Filters are read from the JSON body only, by the exact names in Parameters. Check |
| The response is an error. Read |
An employee I asked for is missing | Sense HR holds no entitlements for them. They are listed in |
Totals look wrong when added up | Records may be in different units. Group by |
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.