Returns the people that match the given filters.

POST /people/search

Group: People Management › People · Operation ID: searchPeople

Open in the interactive reference

Parameters

Name In Type Required Description
Api-Version header "v1" yes The API version this request targets, named by its public identifier. Required on every request; omitting it, or naming a version this company does not have, is answered with 400. This document describes version v1.

Request body

Required, application/json: searchPeopleInput.

Field Type Required Description
filters object yes The filters to apply. A person must match every filter you send.
filters.firstName string no Limits results to people with this first name.
filters.lastName string no Limits results to people with this last name.
filters.name string no Limits results to people with this full name.
filters.email string no Limits results to people with this work email address.
filters.employeeNumber string no Limits results to the person with this business number. The match is exact.
filters.entityName string no Limits results to people in the legal entity with this name. The match is exact.
filters.status string no Limits results to people with this employment status. Accepted values: 'Active', 'Inactive', 'Planned', 'Cancelled'. Any other value matches no person.
filters.employmentCategory string no Limits results to people with this employment category.
filters.externalIdentifier object no Limits results to people with this external identifier. Both fieldName and value are required. Several people may share a value, so this returns the items array, not a single record.
filters.externalIdentifier.fieldName string yes The configured key of the external identifier, a camelCase slug such as 'netsuiteEmployeeId'. It must be the fieldName of an existing employee external-identifier configuration, or the call fails with UNKNOWN_EXTERNAL_IDENTIFIER.
filters.externalIdentifier.value string yes The identifier as the source system holds it. The match is exact.
page object no The pagination controls. Omit for the first page.
page.cursor string no The cursor from the previous response's pagination.nextCursor. Omit on the first request.
page.size number no The maximum number of people per page, between 1 and 200. Defaults to 50. A value above 200 is treated as 200.

Example:

{
  "filters": {
    "firstName": "<firstName>",
    "lastName": "<lastName>",
    "name": "<name>",
    "email": "<email>",
    "employeeNumber": "<employeeNumber>",
    "entityName": "<entityName>",
    "status": "<status>",
    "employmentCategory": "<employmentCategory>",
    "externalIdentifier": {
      "fieldName": "<fieldName>",
      "value": "<value>"
    }
  },
  "page": {
    "cursor": "<cursor>",
    "size": 0
  }
}

Response

200 Success

Under data (searchPeopleOutput):

Field Type Required Description
items array of object yes The people that match this page of the search. An empty array when nothing matches.
items[].id string yes The unique identifier for the person.
items[].employeeNumber string no The person's business number.
items[].firstName string no The person's first name.
items[].lastName string no The person's last name.
items[].middleName string no The person's middle name.
items[].preferredFirstName string no The person's preferred first name.
items[].preferredLastName string no The person's preferred last name.
items[].name string no The person's full name, in first-name-last-name order.
items[].email string no The person's work email address.
items[].status string no The current employment status of the person. Possible values: 'Active', 'Inactive', 'Planned', 'Cancelled'.
items[].employmentCategory string no The employment category assigned to this person.
items[].startDate string no The employment start date. Format YYYY-MM-DD.
items[].endDate string no The employment end date. Format YYYY-MM-DD. Absent while the person is still employed.
items[].probationEndDate string no The probation end date. Format YYYY-MM-DD. Absent when no probation period applies.
items[].jobId string no The identifier of this person's active primary job. Absent when the person has no active primary job. There is no endpoint for it.
items[].departmentName string no The name of the department this person belongs to. Absent when no department is assigned.
items[].positionName string no The position or job title assigned to this person. Absent when no position is assigned.
items[].managerName string no The full name of this person's primary manager. Absent when there is no active primary job or no manager assigned to it.
items[].compensation object no The person's current active compensation record. Absent when no compensation record exists.
items[].compensation.amount object no The base salary as a currency amount.
items[].compensation.amount.currency string no The currency of the base salary. Format ISO 4217, for example 'USD'.
items[].compensation.amount.amount string (decimal) no The numeric value of the base salary, in the given currency.
items[].compensation.paymentFrequency string no The frequency at which this person is paid. Possible values: 'monthly', 'biweekly', 'weekly', 'yearly'.
items[].compensation.unit string no The unit the base salary is measured in. Possible values: 'annually', 'quarterly', 'monthly', 'semiMonthly', 'weekly', 'biWeekly', 'daily', 'hourly', 'fixed'.
items[].compensation.monthlyAmount object no The base salary converted to a monthly amount. Only the 'annually' and 'hourly' units are converted. For every other unit this repeats the base salary unchanged and is not a monthly figure.
items[].compensation.monthlyAmount.currency string no The currency of the monthly-equivalent salary. Format ISO 4217, for example 'USD'.
items[].compensation.monthlyAmount.amount string (decimal) no The numeric value of the monthly-equivalent salary, in the given currency.
items[].compensation.salaryType string no The name of the compensation type. Absent when none is assigned.
items[].compensation.salaryCode string no The code of the compensation type. Absent when the type has no code or none is assigned.
items[].compensation.startDate string no The date from which this compensation record is effective. Format YYYY-MM-DD.
items[].compensation.endDate string no The date on which this compensation record expires. Format YYYY-MM-DD. Absent when it is open-ended.
items[].entityName string no The name of the legal entity this person belongs to.
items[].locationName string no The name of this person's work location. Absent when none is assigned.
items[].customFields UnknownObject no The person's custom field values, as key-value pairs of field name and value.
items[].lastModifiedDate string (date-time) yes The date and time the person record last changed, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ.
items[].externalIdentifiers array of object no The external identifiers owned by other systems, at most one per fieldName. Absent when the person has none.
items[].externalIdentifiers[].fieldName string yes The configured key of the external identifier, a camelCase slug such as 'netsuiteEmployeeId'. It is the fieldName of an existing employee external-identifier configuration.
items[].externalIdentifiers[].value string yes The identifier as the source system holds it.
items[].externalIdentifiers[].externalUrl string no An absolute http(s) link to the object in the source system. Absent when none is stored.
pagination object yes The pagination details for this page.
pagination.nextCursor string no The cursor for the next page. Pass it as page.cursor. Absent on the last page.
pagination.hasMore boolean yes Whether more results remain after this page.

Errors

Code Status
UNKNOWN_EXTERNAL_IDENTIFIER 400

Statuses