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.

To get started you must first install the Employee Core Data API from the Automate Hub.

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

Authorization: your-api-key-here

Two important points:

  • 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 may optionally be restricted to one or more approved source IP addresses. If this is enabled for you, requests must originate from a registered public IP or they will be rejected. If it is not enabled, requests are accepted from any IP (subject to a valid API key).

To register or change your approved IP addresses, contact your Sense HR representative.

Making a request

Methods

POST

Content-Type

application/json (when sending a body)

Body

Optional. Used to filter the results — see below.

POST is recommended because the request options are supplied in a JSON body.

Request body parameters

Both parameters are optional. Send an empty body (or no body) to get all active employees.

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 specific employees, identified by their senseHrId.

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 either 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.

Example requests

All active employees (empty body):

bash

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:

bash

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:

bash

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:

bash

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"         ]       }'

Response

A successful request returns HTTP 200 with Content-Type: application/json. The body is an object with a single data property containing an array of employee records:

json

{   "data": [     { "senseHrId": "…", "firstName": "…", "...": "…" }   ] }

Employee fields

Field

Type

Description

senseHrId

string

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

firstName

string

Employee's first name.

lastName

string

Employee's last name.

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

null

EmployeeId entered into the Employment details screen

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 manager(s). May be an empty array. See below.

status

string

Employment status: Active or Leaver.

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.

Example response

json

{   "data": [     {       "senseHrId": "111e3eb6-e8c9-47d7-9626-043439d7e293",       "firstName": "Tia",       "lastName": "Perry",       "emailAddress": "[email protected]",       "dateOfBirth": "1972-08-08T00:00:00.000Z",       "gender": "Female",       "employeeId": 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",       "emailAddress": "[email protected]",       "dateOfBirth": "1990-01-24T00:00:00.000Z",       "gender": "Male",       "employeeId": null,       "startDate": "2011-05-09T00:00:00.000Z",       "jobTitles": ["HR Assistant"],       "locations": ["Doncaster"],       "departments": ["HR"],       "companies": [],       "lastDayOfEmployment": null,       "lineManagers": [],       "status": "Active"     }   ] }

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 contain a single value, several values, or (for companies) be empty.

  • 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.

  • Ordering. The order of records in data 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.

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.

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.

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

Related Articles
Did this answer your question?