Critical behaviors
Read the full People read API contract before integrating. Summary:
- Request field IDs — Use dot notation from Fields metadata (e.g.
root.id,work.department). This is the canonical field ID — a stable identifier that does not change when a field is moved to another category. A field ID may look like a path (category.field), but it is not a live path to the current category; always use metadatacategoryIdfor permissions, not the prefix in the field ID string. - Response field keys — Returned with slash notation (e.g.
/root/id). The same employee may also include nested category objects (e.g.work.siteIdalongside/work/siteId). - Single employee — One employee per call (path
identifier). Not bulk search; use Search for employees for many employees. No pagination. - Silent omission — Fields in
fields[]without permission or with invalid IDs are omitted (200 OK, no warning). Always validate the response against your request. - Permissions — Grant the service user View on each field's category (
categoryIdfrom metadata), not per field ID. - Custom fields — Not in default responses; request each metadata
idinfields[]. See Custom employee fields (category fields).
Setup walkthrough: Read employee data · Field types & humanReadable: Fields metadata
Bad request. The request contains incorrect parameters or syntax errors. Please review the request body
Forbidden. The service user does not have permissions to access this table or employees. Check the permissions as explained in the endpoint description.
"Too Many Requests" error. This indicates that you've exceeded the rate limit for requests. Please verify that you are using the correct endpoint with the POST method. Additionally, check the HTTP headers for rate limit information, such as the number of requests allowed and the time until the limit resets. For more details, see Rate Limiting.