List Employees

Changed on Nov 3, 2026

Lists all employees in the authenticated caller's company as a cursor-paginated list. Use this to list employees, fetch the employee roster, or batch-lookup multiple employees by ID.

Response shape. 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. IDs for filter[ids] come from prior responses of this endpoint.

Employee photos. 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.

Permissions. Field values the caller cannot read are returned as null, and the names of those suppressed fields are listed on the record in _restrictedFields. On an unfiltered request an employee remains in data even when the caller can read none of the requested fields: employeeId still carries its real value, every unreadable field is null and named in _restrictedFields, values that are not permission-gated such as photoUrl may still be populated, and meta.total counts the row. Separately, 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, so a name search can return meta.total: 0 even though matching employees exist. Neither an empty result nor a fully nulled row means no such employee exists.

Counts and aggregates are only valid when the caller can read every field being grouped on. A caller with full access can safely count and group these rows. A restricted caller cannot: unreadable values come back null and filtered queries drop employees entirely, so grouping what such a caller receives understates the real figures and produces a confident but wrong total. Before reporting any count, headcount, department or location breakdown, or turnover figure, compare meta.total against the number of rows carrying readable values for the field in question. If those differ, the aggregate is incomplete: either state plainly how many employees were actually readable, or use Get Data from Dataset (v2) (get-data-from-dataset-v2) or the custom report endpoints instead, which require broader access and fail loudly rather than returning a partial answer.

Related endpoints. 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). To look up information published in a coworker's company directory entry, such as job title, department, location, work contact details, or who they report to, use Get Employees Directory (get-employees-directory), which is governed by directory sharing settings rather than by per-employee record permissions and is available when directory or org-chart access is shared with the caller's access level.

OAuth Scopes: employee, employee:job, employee:name, employee_directory, sensitive_employee:protected_info

get/api/v1/employees