Skip to main content

Employee Core Data API

Retrieve employee records from Sense HR through a single endpoint. One call returns the full set of employees (or a filtered subset), each with their personal details, role information, and line managers.

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 Bearer prefix.

  • The header name is case-insensitive: Authorization and authorization both 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

POST

Content-Type

application/json (when sending a body)

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

listType

string

ACTIVE

Which employees to include. One of ACTIVE, LEAVERS or ACTIVE_AND_LEAVERS.

senseHrId

string or array of strings

(all employees)

Restrict the results to one or more employees, identified by their senseHrId.

IncludeWorkPattern

boolean

false

When true, each employee record includes a workingHourPattern array.

listType behaviour

  • Accepts ACTIVE, LEAVERS or ACTIVE_AND_LEAVERS.

  • Case-insensitive: active is treated the same as ACTIVE.

  • If omitted, empty or set to an unrecognised value, it defaults to ACTIVE.

senseHrId behaviour

  • If omitted, all employees matching the listType are 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 true to include each employee's working hour patterns. The string "true" is also accepted, in any case.

  • If omitted, false or any other value, working hour patterns are not returned and the workingHourPattern field 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

senseHrId

string

Unique, stable Sense HR identifier for the employee. Use it to reference or match a record.

firstName

string

Employee's first name.

lastName

string

Employee's last name.

KnownAs

string | null

The name the employee prefers to be known by. null if not held.

emailAddress

string

Employee's email address.

dateOfBirth

string | null

Date of birth, ISO 8601 (UTC), e.g. 1990-01-24T00:00:00.000Z. null if not held.

gender

string | null

Gender label, e.g. Male, Female. null if not held.

employeeId

string | null

Employee ID entered on the Employment details screen. null if not held.

employmentType

string | null

Employment type entered on the Employment details screen. null if not held.

startDate

string | null

Employment start date, ISO 8601 (UTC). null if not held.

jobTitles

string[]

One or more job titles. An employee may hold several.

locations

string[]

One or more work locations.

departments

string[]

One or more departments.

companies

string[]

One or more (sub)companies. May be an empty array.

lastDayOfEmployment

string | null

Leaver date, ISO 8601 (UTC). null for current employees.

lineManagers

object[]

The employee's line managers. May be an empty array. See below.

status

string

Employment status: Active or Leaver.

workingHourPattern

object[]

The employee's working hour patterns. Only present when IncludeWorkPattern is true. May be an empty array. See below.

lineManagers object

Field

Type

Description

senseHrId

string

The manager's unique Sense HR identifier.

name

string

The manager's full name.

emailAddress

string

The manager's email address.

workingHourPattern object

Only returned when the request sets IncludeWorkPattern to true.

Field

Type

Description

workingHourPatternId

string

Identifier of the working hour pattern.

workingHourPatternName

string

Name of the pattern.

fullTimeHours

number

Full-time hours for the pattern.

contractedHours

number

The employee's contracted hours on this pattern.

fte

number

Full-time equivalent, e.g. 0.8.

effectiveFrom

string | null

Date the pattern applies from, ISO 8601 (UTC). null if not held.

effectiveTo

string | null

Date the pattern ends, ISO 8601 (UTC). null if it has no end date.

isCurrent

boolean

true for the pattern in effect today.

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. senseHrId is 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 as null.

  • Multi-value fields. jobTitles, locations, departments and companies are always arrays, because an employee can have more than one. They may hold one value, several values or (for companies) none.

  • Line managers. lineManagers is an array: an employee may have zero, one or several. Each entry includes the manager's own senseHrId, which you can cross-reference against other records.

  • Known as. KnownAs is the employee's preferred name. Fall back to firstName when it is null.

  • Working hour patterns. workingHourPattern is an array because an employee's pattern can change over time. Each entry has its own effective dates; use isCurrent to find the pattern in effect today. The field is only present when the request sets IncludeWorkPattern to true.

  • 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 senseHrId filter, the endpoint returns every employee matching the listType, so expect the full population. Adding working hour patterns increases the size further.

Troubleshooting

Symptom

Likely cause

Request rejected / unauthorized

Missing or incorrect Authorization header. Confirm the value is the raw API key with no Bearer prefix.

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 POST. The endpoint only accepts POST.

Empty or unexpectedly full result when filtering by senseHrId

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

listType was omitted or unrecognised and defaulted to ACTIVE. Send a valid listType value.

No workingHourPattern in the response

IncludeWorkPattern was omitted, false, or not sent as true. Check the request body is being sent as JSON.

For access, API keys, IP registration or any other query, contact your Sense HR representative.

Did this answer your question?