Retrieve day-by-day attendance detail from Sense HR — each employee's scheduled pattern alongside their actual clock-in and clock-out times, breaks, and any planner events falling on the day. One call returns every day in a date range, for all employees or a specified subset.

This endpoint is asynchronous: a request is submitted, and the data is collected and retrieved in a second call. The submission is a POST; the retrieval is a GET. See Making a request.

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.

Send the same Authorization header on the follow-up request as well as the initial one.

Because assembling attendance detail can take longer than a single HTTP request should wait for, this endpoint works in two steps. Each step uses a different method:

The methods are not interchangeable. A GET to the endpoint URL will not submit a request and will not return a Location header, and the retrieval URL accepts GET only.

Send a POST request to your endpoint URL, with parameters supplied in the query string:

No request body is required — the parameters travel in the query string, and the POST carries nothing. Send Content-Length: 0, or whatever your client does by default for a body-less POST.

The response is HTTP 202 Accepted. It contains no data. What matters is the Location response header, which holds the path where your result will become available:

http

The path is relative. Prefix it with the API host to get the URL to call:

Do not attempt to construct this URL yourself, and do not assume the token has any particular length or character set. Always read it from the Location header of the response you just received. Each submission produces a new token.

Note that 202 is not a redirect, so HTTP clients do not follow Location automatically. curl -L, for example, will not follow it — you must issue the second request yourself.

Each POST submits a new request and returns a new token. Submitting is not idempotent, so a client that retries the submission on a network timeout will queue a second identical job. Retry the retrieval, not the submission.

Send a GET request to the URL from the Location header. Only GET is accepted here — do not POST to the retrieval URL.

There is no separate "status" call and no progress information — a 202 simply means "not yet". Keep requesting the same URL until you receive a 200.

Recommended polling behaviour

Larger requests take longer to prepare. A single employee over a few days will typically be ready almost immediately; all employees across a full 30-day window takes longer.

Parameters are supplied in the query string of the Step 1 POST only. They are not accepted on the retrieval GET, which returns whatever the submission asked for. All three are optional — a bare submission with no parameters returns the last 30 days, ending today.

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, and impossible dates such as 2026-02-30 are rejected.

The range may not exceed 30 days. This is a hard limit: attendance detail returns one record per employee per day, so an unbounded range would return an unworkable volume of data.

A range you supply is either honoured or rejected. It is never silently narrowed — if the endpoint cannot serve what you asked for, it tells you rather than returning a different period that looks correct.

Accepted, no error:

Rejected with a 400:

Empty parameters (?startDate=&endDate=) count as not supplied, and get the default range rather than an error.

To cover a longer period, issue consecutive requests of 30 days or fewer and combine the results yourself. See Error responses for the response shape, and Confirming the window you got for how to assert the range you were served.

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

Step 1 — submit a request for the default range (last 30 days). Note -X POST, and -i so the response headers are printed:

bash

http

Step 2 — retrieve the result. This is a GET, which is curl's default, so no -X is needed:

bash

Repeat until the status is 200 rather than 202.

Submitting for one employee over a specific range:

bash

Be careful not to let curl change the method for you: if you add -d or -F to a request, curl sets POST and moves your data into the body, and if you add -L to a POST, curl may downgrade the followed request to GET. Neither is wanted here — keep the parameters in the URL and don't follow redirects.

bash

javascript

Once ready, the retrieval request returns HTTP 200 with Content-Type: application/json. The body carries a meta object describing the request that was served, and a data array of day records:

json

One record represents one employee on one day. A request covering 10 employees over 30 days returns up to 300 records. Non-working days are included — see Non-working days.

If no records fall within the range, data is an empty array. The order of records is not guaranteed.

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.

Each entry in events describes one planner event falling on that day for that employee.

A day can carry more than one event. A multi-day absence appears on each day it covers, so the same event is repeated across consecutive records — this is the intended behaviour and is what makes this endpoint suitable for day-level reporting.

Unlike the Calendar Events API, public holidays are not filtered out here, because a public holiday is a legitimate explanation for a day with a pattern but no clock-ins.

json

A request that cannot be served returns HTTP 400 with an error object in place of meta and data:

json

Validation happens after submission. The POST returns 202 before the parameters have been examined, so a rejection cannot be reported there — it arrives on the retrieval GET. A rejected request therefore looks like any other: 202, then a 400 where you expected a 200. Treat any non-202, non-200 status from the retrieval URL as terminal and stop polling.

Treat the code list as open. New codes may be added, so branch on the codes you handle and fall back to surfacing message for anything unrecognised.

A record is identified uniquely by the combination of senseHrId and date. There is no single-field record identifier. If you are caching records or performing upserts, key on both fields.

eventId inside events identifies the underlying planner event, which may span several days and several employees, so it is not unique within a response.

meta.startDate and meta.endDate are the range that was actually served. Where a default was applied — because you supplied one date or none — they are the only way to know what period your records cover.

If your client cares about the period, assert on meta rather than assuming your parameters took effect:

javascript

The same applies to the employee filter: meta.senseHrIds is what was applied, and an empty array means every employee was returned. That check is worth having, because an unrecognised senseHrId is still dropped silently — see senseHrId behaviour.

Each record holds two kinds of information, and the distinction matters:

Comparing the two is the point of this endpoint — lateness, early finishes, missed breaks, and unexplained absence all come from the gap between them. But a gap is not by itself evidence of anything: a null clock-in on a scheduled working day may mean the employee was absent, or that they were working somewhere clocking isn't used, or that a device failed. Check events before drawing a conclusion.

Days that are not scheduled working days are included in the response, with isWorkingDay: false and, typically, no pattern or clock times. Weekends and rest days therefore appear as records.

If you only want scheduled days, filter on isWorkingDay === true. Do not infer a non-working day from the absence of a pattern time, since a working day can also lack one.

breakDurationInMins is what was recorded; patternBreakDurationInMins is what the pattern allows. They are separate values and neither is derived from the other.

A recorded break of 0, or null, does not reliably mean no break was taken — it may mean breaks are not clocked for that employee. Treat break data as indicative unless you know clocking is enforced for the population you are reporting on, and take working time compliance figures from Sense HR directly rather than calculating them here.

earliestClockIn and latestClockOut are the outer bounds of the day, not a list of every clock event. Where an employee clocks in and out several times, the intervening activity is not represented.

Do not treat latestClockOut minus earliestClockIn as hours worked. That figure includes every break and gap in the day. It is a span, not a total.

Because the range is capped at 30 days, reporting over a quarter or a year means several requests. Each is an independent submit-and-poll cycle. Run them sequentially rather than firing many submissions at once, and note that records are per employee per day, so a year of data for a large workforce is a substantial volume — consider narrowing by senseHrId as well as by date.

Clock-in and clock-out times are personal data describing when identifiable individuals started and finished work, and analysing them constitutes monitoring of workers. Anyone holding your API key can retrieve them.

Before consuming this endpoint, satisfy yourself that:

If you would prefer clock times withheld from your endpoint entirely, contact us and we can arrange that.

I got a 202 and no data. That is expected on the submission. Read the Location response header and issue a GET to that path, prefixed with the API host. See Making a request.

My submission returned no Location header. Check the method. Submitting requires POST — a GET to the endpoint URL does not submit a request and returns no Location. In curl, that means -X POST.

My retrieval failed, or returned nothing. Check the method here too. The retrieval URL accepts GET only. A POST to it will not return your data. Note that some HTTP clients preserve the method across a whole session or reuse a configured default — if your submission is a POST, make sure the retrieval isn't one as well.

I keep getting 202 from the retrieval URL. The result is not ready yet. Continue polling every few seconds. If it has not resolved within a minute or so, check that you are calling the URL exactly as returned in Location — a truncated or re-encoded token will not resolve — and that you are sending the Authorization header.

My client followed the Location header automatically and got nothing. 202 is not a redirect status, so it should not be followed automatically. Some clients and gateways treat any Location header as a redirect. Disable redirect following and handle the second request explicitly.

My retrieval returned a 400 with DATE_RANGE_TOO_WIDE. The range exceeded 30 days. Split the period into consecutive requests of 30 days or fewer and combine the results. The maxDays field in the error carries the current limit.

My retrieval returned a 400 with DATE_INVALID. A date was not a real calendar date in YYYY-MM-DD form. The requested object in the error echoes what was received, which usually makes the problem obvious — 01/09/2026 and 2026-02-30 are both rejected. Note this is a change from earlier behaviour: malformed dates used to fall back to a default range silently.

I get fewer records than expected, but no error. Check meta.startDate and meta.endDate. If you supplied only one date, or none, a default window was applied and meta tells you which. Also check meta.senseHrIds — an empty array means no employee filter was applied.

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.

Clock times are null on a day the employee worked. Only recorded clocking appears here. If the employee does not clock, or clocked on a system not connected to Sense HR, the fields are null even though the day was worked. Check events and isWorkingDay for context before treating it as absence.

Weekends are in my results. Non-working days are returned by design. Filter on isWorkingDay.

No response, or an error rather than a 202. Confirm you are sending POST, and that 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 — employee records including names, roles, departments, and line managers.

Calendar Events API — planner events as events rather than as days: one record per event, with approval status, duration, and sickness reason. Use it when you need the event itself; use the Attendance API when you need the day.

senseHrId is shared across all three endpoints, so records can be joined directly.