List Employees

get

https://{companyDomain}.bamboohr.com/api/v1/employees

Returns a cursor-paginated collection of employees for the authenticated caller's company. 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. 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. Use this for lightweight directory-style listings and batch lookups by ID. For a single employee with the full set of fields, use Get Employee (get-employee) instead. For complex filtering (date ranges, multi-field predicates, OR/IN logic), arbitrary sorting, or tabular reports across many fields, use Get Data from Dataset (v2) (get-data-from-dataset-v2) instead.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Query Params

filter

object

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.

sort

string

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.

fields

array of objects

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.

fields

page

object

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.

Responses

401

Unauthorized.

429

Too many requests.

500

Internal server error.

200Paginated list of employees.