Before using this endpoint — see the People read API contract and People API (rate limits, permissions table, troubleshooting):

Bulk read: returns employee field data for many employees in one call.
No pagination: each successful call returns all matching employees in one employees array (every employee the service user can access when filters is omitted, or every employee matching a root.id / root.email filter; up to 400 field IDs in fields[]). See Pagination and result scope.
POST (not GET): the request body selects fields and filters.
Field IDs (requests): use dot notation from Fields metadata (e.g. root.id). This is the canonical field ID — stable when a field moves categories; not a live category path. Use metadata categoryId for permissions.
Field keys (responses): slash notation (e.g. /root/id). The same employee may also include nested category objects (e.g. work.siteId alongside /work/siteId).
Silent omission: entries in fields[] without permission or with invalid IDs are omitted (200 OK, no warning).
Filters: only root.id and root.email with operator equals; other field paths return 400.
Permissions: grant the service user View on each field's category (categoryId from metadata), not per field ID.
Default fields: if fields[] is omitted, returns fields from root, about, employment, and work (subject to permissions).
Custom fields: not included in default responses; request each metadata id in fields[] and grant category permission. See Custom employee fields (category fields).
Scope: employee fields only — not table rows (Employee Tables) or positions (Workforce Planning).
Large companies (recommended for integrators and AI agents): to read all employees, first call with fields: ["root.id"] only, then batch follow-up calls with a root.id filter and the full fields[] you need (e.g. 50–200 IDs per call). Do not fetch all employees with many fields in one unfiltered request. See Recommended pattern for large companies.
showInactive (defaults to false): when omitted or false, only active employees are returned. Set showInactive: true for terminated, inactive, former, or leaver employees — required for AI/MCP requests such as "find terminated employees" or "include inactive employees". See showInactive.

Testing notes:

Use the testing widget's Try It! option to test this endpoint.
Use Examples > Request Example to see body parameters.
Explore the response payload using the Example in the Response panel (human-readable and machine-format).

200Onboarding Wizards

defaultUnexpected error