Skip to main content
POST
Search employees
The JSON request body may be omitted. Without a companyId filter, the search covers every company allowed by the key. Filters combine with AND. firstName, lastName, fullName, and email use case-insensitive partial matching. employeeId and personId require exact UUID matches. dateOfBirth is a calendar date in YYYY-MM-DD format, and createdFrom is an inclusive lower bound on Employee creation time. Phone matching strips nondigits and uses the last 10 digits of the input. Shorter partial numbers also match. A nonempty phone value with no digits is invalid. Empty-string fields are ignored, and text filters are limited to 100 characters. externalIdSystems accepts payroll_system and hhaexchange. This parameter selects returned external IDs without filtering records. An unsupported externalIdSystems value, an unknown field whose value is not an empty string, or an overlong text filter returns 400 invalid_input with a message naming the value or field. Other invalid filters and request bodies over 1 MiB also return 400 invalid_input. A company ID not accessible to the key returns 403 forbidden. Results include terminated records, exclude archived records, preserve duplicate employee records, and sort by createdAt then id. Pagination reads live data. Full Social Security numbers are not returned. Each Employee object includes top-level participation and coverage fields. Each is null when no applicable record exists.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Optional JSON object. Empty-string fields are ignored. Other unsupported fields return 400 invalid_input. Bodies over 1 MiB return 400 invalid_input.

companyId
string

Optional authorized company filter. Omit to search all companies allowed by the key.

Maximum string length: 100
phone
string

Nondigits are removed. The last 10 digits are used for matching. Partial numbers are accepted, but a nonempty value with no digits is invalid.

Maximum string length: 100
firstName
string

Case-insensitive partial match.

Maximum string length: 100
lastName
string

Case-insensitive partial match.

Maximum string length: 100
fullName
string

Case-insensitive partial match on the full name.

Maximum string length: 100
email
string

Case-insensitive partial match.

Maximum string length: 100
employeeId
string<uuid>

Exact Employee-record UUID match.

dateOfBirth
string<date>

Exact calendar date match.

personId
string<uuid>

Exact Person UUID match.

externalIdSystems
string[]

Specifies which external IDs to return. It does not filter records.

createdFrom
string<date-time>

Set an inclusive lower bound on Employee creation time. Include seconds and a timezone.

limit
integer
default:50
Required range: 1 <= x <= 100
offset
integer
default:0
Required range: 0 <= x <= 9007199254740991
{key}
any

Response

Employee search results.

asOf
string<date-time>
required
employees
object[]
required
pagination
object
required