v1
latestOpenAPI 3.1.02026-07-26294215839.4 KBList Employees
Lists all employees in the authenticated caller's company as a cursor-paginated employee directory. Use this to list employees, browse the company directory, fetch the employee roster, or batch-lookup multiple employees by ID. The response is a JSON object with data (an array of employee records), meta.total (count of all employees matching the filter, not just the current page), meta.page (cursor pagination state), and _links (self, plus next / prev when more pages exist). Each employee record always includes the default identity and job fields, plus any additional fields requested via fields. employeeId is returned as a string and is the internal employee ID — see the employeeId and employeeNumber field documentation in the response schema for the distinction between the internal ID and the editable Employee # value. Field values the caller cannot read are returned as null, and the names of those suppressed fields are listed on the record in _restrictedFields; if the caller cannot read a field used in filter or sort, the affected employee is dropped from the result set entirely to avoid leaking presence. IDs for filter[ids] come from prior responses of this endpoint. For a single employee with the full set of fields, use get-employee. For complex filtering, arbitrary sorting, or tabular reports across many fields, use Get Data from Dataset (v2) (get-data-from-dataset-v2). Each record includes a photoUrl field with a time-limited signed URL. This is the recommended way for AI connectors to display or link to an employee photo, since fetching raw photo bytes through get-employee-photo produces base64 payloads too large for an AI model to consume reliably.
OAuth Scopes: employee, employee:job, employee:name, employee_directory, sensitive_employee:protected_info
Query parameters
Filters used to match employees. Encode filter properties using deepObject style (filter[firstName]=Ava). Multiple filter fields are combined with AND. filter[ids] accepts either repeated keys (filter[ids][]=123&filter[ids][]=124) or a single comma-separated string (filter[ids]=123,124); both forms are supported.
{
"ids": [
123,
124
]
}Comma-separated list of sortable fields. Prefix a field with - for descending order. Allowed fields: employeeId, firstName, lastName, preferredName, jobTitleName, status. Nulls sort first in ascending order and last in descending order. An invalid sort field returns a BadRequest error.
Additional fields to include in each employee record beyond the default set. The canonical form is a comma-separated list (fields=workEmail,mobilePhone); for backward compatibility the endpoint also accepts the bracket-array form (fields[]=workEmail&fields[]=mobilePhone). Note: plain repeated keys without brackets (fields=workEmail&fields=mobilePhone) are unreliable — most HTTP stacks keep only the last value, silently dropping earlier ones; use the comma-separated form instead. Unrecognized field names are silently ignored. Returned values are subject to permission checks — fields the caller cannot read are returned as null and their names are listed in the record's _restrictedFields array.
Cursor-based pagination parameters. page[limit] controls page size (default 250, maximum 2500). page[after] and page[before] accept opaque cursors returned in the previous response's meta.page.nextCursor / prevCursor; do not specify both at once. The response's _links.next / _links.prev are pre-built URLs that already encode the correct cursor for the next or previous page.
Response
Paginated list of employees.