Getting started
Install the Employee Core Data API from the Automate Hub first.
Base URL
https://api.automate.sensewp.com/package/http/endpoint/{your-endpoint-id}You receive the full URL, including your unique endpoint ID, 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 value is the API key on its own. There is no
Bearerprefix.The header name is case-insensitive:
Authorizationandauthorizationboth work.
Requests with a missing or incorrect key are rejected.
IP allow-listing (optional)
Your account can be restricted to one or more approved public IP addresses. If this is enabled, requests from any other IP are rejected. If it is not enabled, requests are accepted from any IP that sends a valid API key.
To register or change your approved IP addresses, contact your Sense HR representative.
Making a request
Setting | Value |
Method |
|
Content-Type |
|
Body | Optional. Filters the results and turns on optional data. See below. |
Request body parameters
All parameters are optional. Send an empty body (or no body) to get all active employees without working hour patterns.
Parameter | Type | Default when omitted | Description |
| string |
| Which employees to include. One of |
| string or array of strings | (all employees) | Restrict the results to one or more employees, identified by their |
| boolean |
| When |
listType behaviour
Accepts
ACTIVE,LEAVERSorACTIVE_AND_LEAVERS.Case-insensitive:
activeis treated the same asACTIVE.If omitted, empty or set to an unrecognised value, it defaults to
ACTIVE.
senseHrId behaviour
If omitted, all employees matching the
listTypeare returned.If supplied, only the employees with those IDs are returned. Accepts a single ID string or an array of ID strings.
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 all employees are returned.
IncludeWorkPattern behaviour
Set to
trueto include each employee's working hour patterns. The string"true"is also accepted, in any case.If omitted,
falseor any other value, working hour patterns are not returned and theworkingHourPatternfield is left out of each record entirely. Existing integrations are unaffected.The parameter name is also accepted as
includeWorkPattern.Including patterns makes the response larger, so only request them when you need them.
Example requests
All active employees (empty body):
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 '{}'Leavers only:
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 '{ "listType": "LEAVERS" }'Active and leavers together:
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 '{ "listType": "ACTIVE_AND_LEAVERS" }'Specific employees by ID:
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": [ "111e3eb6-e8c9-47d7-9626-043439d7e293", "6e6d2b45-5701-47e3-b64d-525b307dd8f1" ] }'Active employees with working hour patterns:
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 '{ "IncludeWorkPattern": true }'The parameters can be combined. For example, specific employees, including leavers, with working hour patterns:
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 '{ "listType": "ACTIVE_AND_LEAVERS", "senseHrId": ["111e3eb6-e8c9-47d7-9626-043439d7e293"], "IncludeWorkPattern": true }'Response
A successful request returns HTTP 200 with Content-Type: application/json. The body is an object with a single data property holding an array of employee records:
{ "data": [ { "senseHrId": "…", "firstName": "…", "...": "…" } ] }Employee fields
Field | Type | Description |
| string | Unique, stable Sense HR identifier for the employee. Use it to reference or match a record. |
| string | Employee's first name. |
| string | Employee's last name. |
| string | null | The name the employee prefers to be known by. |
| string | Employee's email address. |
| string | null | Date of birth, ISO 8601 (UTC), e.g. |
| string | null | Gender label, e.g. |
| string | null | Employee ID entered on the Employment details screen. |
| string | null | Employment type entered on the Employment details screen. |
| string | null | Employment start date, ISO 8601 (UTC). |
| string[] | One or more job titles. An employee may hold several. |
| string[] | One or more work locations. |
| string[] | One or more departments. |
| string[] | One or more (sub)companies. May be an empty array. |
| string | null | Leaver date, ISO 8601 (UTC). |
| object[] | The employee's line managers. May be an empty array. See below. |
| string | Employment status: |
| object[] | The employee's working hour patterns. Only present when |
lineManagers object
Field | Type | Description |
| string | The manager's unique Sense HR identifier. |
| string | The manager's full name. |
| string | The manager's email address. |
workingHourPattern object
Only returned when the request sets IncludeWorkPattern to true.
Field | Type | Description |
| string | Identifier of the working hour pattern. |
| string | Name of the pattern. |
| number | Full-time hours for the pattern. |
| number | The employee's contracted hours on this pattern. |
| number | Full-time equivalent, e.g. |
| string | null | Date the pattern applies from, ISO 8601 (UTC). |
| string | null | Date the pattern ends, ISO 8601 (UTC). |
| boolean |
|
Example response
Default request (no IncludeWorkPattern):
{ "data": [ { "senseHrId": "111e3eb6-e8c9-47d7-9626-043439d7e293", "firstName": "Tia", "lastName": "Perry", "KnownAs": "Tia", "emailAddress": "[email protected]", "dateOfBirth": "1972-08-08T00:00:00.000Z", "gender": "Female", "employeeId": null, "employmentType": null, "startDate": "2012-12-10T00:00:00.000Z", "jobTitles": ["Customer Services Advisor", "Developer"], "locations": ["Manchester", "Edinburgh"], "departments": ["Customer Services", "Engineering"], "companies": ["Welsh co"], "lastDayOfEmployment": null, "lineManagers": [ { "senseHrId": "6e6d2b45-5701-47e3-b64d-525b307dd8f1", "name": "Aida Welsh", "emailAddress": "[email protected]" }, { "senseHrId": "5b571355-b2f8-437e-9d86-782e5a43e95f", "name": "Ben Greg", "emailAddress": "[email protected]" } ], "status": "Active" }, { "senseHrId": "b5ef79e6-1170-428d-80ce-0734d0c09269", "firstName": "Owen", "lastName": "Redmond", "KnownAs": null, "emailAddress": "[email protected]", "dateOfBirth": "1990-01-24T00:00:00.000Z", "gender": "Male", "employeeId": null, "employmentType": null, "startDate": "2011-05-09T00:00:00.000Z", "jobTitles": ["HR Assistant"], "locations": ["Doncaster"], "departments": ["HR"], "companies": [], "lastDayOfEmployment": null, "lineManagers": [], "status": "Active" } ] }With "IncludeWorkPattern": true, each record gains a workingHourPattern array (other fields shortened here):
{ "data": [ { "senseHrId": "111e3eb6-e8c9-47d7-9626-043439d7e293", "firstName": "Tia", "lastName": "Perry", "KnownAs": "Tia", "...": "…", "status": "Active", "workingHourPattern": [ { "workingHourPatternId": "7", "workingHourPatternName": "Standard 37.5 hours", "fullTimeHours": 37.5, "contractedHours": 37.5, "fte": 1, "effectiveFrom": "2012-12-10T00:00:00.000Z", "effectiveTo": "2024-12-31T00:00:00.000Z", "isCurrent": false }, { "workingHourPatternId": "12", "workingHourPatternName": "Part time 30 hours", "fullTimeHours": 37.5, "contractedHours": 30, "fte": 0.8, "effectiveFrom": "2025-01-01T00:00:00.000Z", "effectiveTo": null, "isCurrent": true } ] } ] }Notes and conventions
Identifier.
senseHrIdis the stable key for an employee. Use it, not list position, to reference, cache or reconcile records.Dates. All dates are ISO 8601 in UTC with a zero time component (
T00:00:00.000Z); treat them as calendar dates. A date that isn't held is returned asnull.Multi-value fields.
jobTitles,locations,departmentsandcompaniesare always arrays, because an employee can have more than one. They may hold one value, several values or (forcompanies) none.Line managers.
lineManagersis an array: an employee may have zero, one or several. Each entry includes the manager's ownsenseHrId, which you can cross-reference against other records.Known as.
KnownAsis the employee's preferred name. Fall back tofirstNamewhen it isnull.Working hour patterns.
workingHourPatternis an array because an employee's pattern can change over time. Each entry has its own effective dates; useisCurrentto find the pattern in effect today. The field is only present when the request setsIncludeWorkPatterntotrue.Ordering. The order of records in
data, and of entries in its arrays, is not guaranteed; do not rely on it.Result size. With no
senseHrIdfilter, the endpoint returns every employee matching thelistType, so expect the full population. Adding working hour patterns increases the size further.
Troubleshooting
Symptom | Likely cause |
Request rejected / unauthorized | Missing or incorrect |
Request rejected despite a correct key | Your source IP may not be on the allow-list (if enabled for your account). Confirm your public egress IP is registered. |
Request rejected with a correct key and IP | The request was not sent as |
Empty or unexpectedly full result when filtering by | One or more IDs were not in a valid format and were ignored; if all were invalid, all employees are returned. Check the IDs sent. |
Got active employees when you wanted leavers |
|
No |
|
For access, API keys, IP registration or any other query, contact your Sense HR representative.