Skip to main content
POST
Search persons
The JSON request body may be omitted. Without a companyId filter, the search covers every company allowed by the key. firstName, lastName, fullName, and email use case-insensitive partial matching on an employment. employeeId selects a matching employment by UUID. personId selects a Person by UUID. dateOfBirth is a calendar date in YYYY-MM-DD format, and createdFrom is an inclusive lower bound on Person 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 and selects returned IDs without filtering people. Filters combine with AND. Company, name, email, phone, date-of-birth, and employee-ID filters must match the same authorized employment. They select people without trimming a matching person’s returned employments array. 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 return each person once with all their non-archived employments in credential-authorized companies, including terminated records. Each employment is a complete Employee object with top-level participation and coverage. Pagination applies to people, not employments, and sorts by Person createdAt then id. Employee records without a Person link remain available through Search employees.

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.

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 on an authorized employment.

Maximum string length: 100
lastName
string

Case-insensitive partial match on an authorized employment.

Maximum string length: 100
fullName
string

Case-insensitive partial match on an authorized employment's full name.

Maximum string length: 100
email
string

Case-insensitive partial match on an authorized employment.

Maximum string length: 100
employeeId
string<uuid>

Exact Employee-record UUID match on an authorized employment.

dateOfBirth
string<date>

Exact calendar date match on an authorized employment.

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 Person 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

Person search results.

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