Skip to main content
POST
Search employees
Search filters combine with AND. A nonempty companyId is required. Supplied first and last names must be nonempty. Phone input may include punctuation or an optional leading 1, but must normalize to exactly 10 digits. externalIdSystems accepts payroll_system and hhaexchange; it selects returned external IDs without filtering records. An unsupported externalIdSystems value returns 400 invalid_input with a message naming the value. Other invalid filters and request bodies over 1 MiB also return 400 invalid_input. A company outside the key’s policy returns 403 forbidden. Results include terminated 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

JSON request body. Bodies over 1 MiB return 400 invalid_input.

companyId
string
required

Required authorized company ID.

Minimum string length: 1
phone
string

Digits must normalize to exactly 10; an optional leading 1 is removed.

firstName
string

Case-insensitive partial match.

Minimum string length: 1
lastName
string

Case-insensitive partial match.

Minimum string length: 1
personId
string<uuid>

Exact Person UUID match.

externalIdSystems
enum<string>[]

Selects returned external IDs; does not filter records.

Available options:
payroll_system,
hhaexchange
createdFrom
string<date-time>

Inclusive creation-time lower bound.

createdBefore
string<date-time>

Exclusive creation-time upper bound.

limit
integer
default:50
Required range: 1 <= x <= 100
offset
integer
default:0
Required range: x >= 0

Response

Employee search results.

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