Read company employee fields by employee ID.

post

https://api.hibob.com/v1/people/{identifier}

Single-employee read endpoint (not bulk search): returns field data for one employee identified by backend ID or email in the path in a single response. No pagination. For many employees in one call, use Search for employees. See Pagination and result scope. This endpoint uses POST (not GET) because the request body selects fields.

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

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).
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).

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).

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 metadata categoryId for 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.siteId alongside /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.
Read-after-update consistency — 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.
Permissions — Grant the service user View on each field's category (categoryId from metadata), not per field ID.
Custom fields — Not in default responses; request each metadata id in fields[]. See Custom employee fields (category fields).

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

Path Params

identifier

string

required

The backend-id of the Employee. Retrieve this ID from the database.
For testing purposes, you can pull it from the URL in Bob when viewing the employee. For example, if the URL in Bob is "https://app.hibob.com/employee-profile/3332883884017713238" you should copy the "3332883884017713238".
Alternaticely you can provide the employee's email address.

Body Params

Read request content that allows you to select fields and other options

fields

array of strings

An optional list of field IDs to return. Use dot notation as returned by Fields metadata (e.g. root.id, work.department). This is the canonical field ID. When not specified, a default set of fields and categories are returned including:

Basic employee fields like: name, id, avatar URL, creation date, etc.

Basic categories:

About
Work

Fields without service-user permission or with unknown IDs are silently omitted (200 OK). Response keys use slash notation (e.g. /root/id). See People read API contract.
The complete fields schema is described in the 200 response status section.

fields

humanReadable

string

Defaults to .

A flag that determines the data format to be returned in the response payload. Use this flag to convert "machine format" numeric IDs, such as "1644513820829" to the "human readable" values.

Flag values:

If not sent: will return only machine-format values. If you pass an invalid value it will be ignored and consdiered empty.

Possible values:

APPEND - include the additional "humanReadable" JSON node in the response.

REPLACE - supply only humanReadable values in the JSON response instead of machine-readable values.

Responses

400

Bad request. The request contains incorrect parameters or syntax errors. Please review the request body

403

Forbidden. The service user does not have permissions to access this table or employees. Check the permissions as explained in the endpoint description.

429

"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.

Critical behaviors

200Employee

defaultUnexpected error.