Critical behaviors

Read the full People read API contract before integrating. See also People API (rate limits, permissions table, troubleshooting).

How this endpoint works

• Bulk read — Returns employee field data for many employees in one call. Uses POST (not GET); the request body selects fields, optional filters, and showInactive.
• No pagination — Each successful call returns all matching employees in one employees array. Without filters, that is every employee the service user can access (respecting showInactive). Max 400 field IDs in fields[]. See Pagination and result scope.

Read-after-update consistency

• Stale reads after writes — If you update employee data and then call this endpoint immediately, the response may still show the previous value or null. Wait up to 20 seconds before a follow-up read. See Read-after-update consistency.

Field IDs and responses

• Request field IDs — Use dot notation from Fields metadata (e.g. root.id, work.department). This is the canonical field ID — stable when a field moves categories; not a live category path. Use metadata categoryId for permissions, not the prefix in the field ID string.
• Response field keys — Slash notation (e.g. /root/id). The same employee may also include nested category objects (e.g. work.siteId alongside /work/siteId).
• Silent omission — Fields in fields[] without permission or with invalid IDs are omitted (200 OK, no warning). Always validate the response against your request.
• Default fields — If fields[] is omitted, returns fields from root, about, employment, and work (subject to permissions).
• Custom fields — Not in default responses; request each metadata id in fields[] and grant category permission. See Custom employee fields (category fields).

Filters

• Supported filters — Only root.id and root.email with operator equals. Other field paths return 400.
• Omit when not filtering — Do not send filters: [] or an empty object; that can return 400. Omit the filters property entirely to return all employees the service user can access (respecting showInactive).

showInactive (terminated and former employees)

• Default false — Active employees only (internal.status = Active). Terminated/hired (internal.status = Inactive) are excluded unless showInactive is true.
• Set showInactive: true when the caller needs terminated, hired, or any kind of leave employees.
• Permissions — showInactive: true alone is not enough. The service user must be allowed to access this audience (permission group Access data for must not be limited to Employed-only). See How to read the employee status and showInactive (contract).

Large companies recommendations

For all employees in a large company: do not call once with many fields and no filter.

1. Search with fields: ["root.id"] only (set showInactive: true if leavers are required).
2. Batch follow-up searches with a root.id filter and the fields you need (e.g. 50–200 IDs per call).

See Recommended pattern for large companies.

Permissions

Grant the service user View on each field's category (categoryId from metadata), not per field ID, and audience that includes all the people you want to access. Note that the default is to include only employed employees.

Scope

This endpoint covers employee fields only, including current values of historical tables (e.g., work table columns). It does not include historical Employee Tables rows or Workforce Planning positions.

Request examples (Try It)

Use Examples → Request Example on this page:

Default Try It body omits filters when not filtering.

Setup walkthrough: Read employee data · Field types & humanReadable: Fields metadata