Sign in

v1

latestOpenAPI 3.1.1Proprietary2026-07-26184406877.9 KB
People

Read company employee fields by employee ID.

Single-employee read endpoint (not bulk search): returns field data for <b>one</b> employee identified by backend ID or email in the path in a single response. <b>No pagination.</b> For many employees in one call, use <a href="https://apidocs.hibob.com/reference/post_people-search" target="_blank">Search for employees</a>. See <a href="https://apidocs.hibob.com/docs/people-read-api-contract#pagination-and-result-scope" target="_blank">Pagination and result scope</a>. This endpoint uses POST (not GET) because the request body selects fields. <p><b>Before using this endpoint</b> — see the <a href="https://apidocs.hibob.com/docs/people-read-api-contract" target="_blank">People read API contract</a> and <a href="https://apidocs.hibob.com/reference/people" target="_blank">People API</a> (rate limits, permissions table, troubleshooting):</p> <ul> <li><b>Field IDs (requests)</b>: use dot notation from <a href="https://apidocs.hibob.com/reference/get_company-people-fields" target="_blank">Fields metadata</a> (e.g. <code>root.id</code>). This is the canonical field ID — stable when a field moves categories; not a live category path. Use metadata <code>categoryId</code> for permissions.</li> <li><b>Field keys (responses)</b>: slash notation (e.g. <code>/root/id</code>). The same employee may also include nested category objects (e.g. <code>work.siteId</code> alongside <code>/work/siteId</code>).</li> <li><b>Silent omission</b>: entries in <code>fields[]</code> without permission or with invalid IDs are omitted (200 OK, no warning).</li> <li><b>Permissions</b>: grant the service user <b>View</b> on each field's category (<code>categoryId</code> from metadata), not per field ID.</li> <li><b>Default fields</b>: if <code>fields[]</code> is omitted, returns fields from <code>root</code>, <code>about</code>, <code>employment</code>, and <code>work</code> (subject to permissions).</li> <li><b>Custom fields</b>: not included in default responses; request each metadata <code>id</code> in <code>fields[]</code> and grant category permission. See <a href="https://apidocs.hibob.com/docs/fields-metadata#custom-employee-fields-category-fields" target="_blank">Custom employee fields (category fields)</a>.</li> <li><b>Scope</b>: employee fields only — not table rows (<a href="https://apidocs.hibob.com/reference/employee-tables" target="_blank">Employee Tables</a>) or positions (<a href="https://apidocs.hibob.com/reference/workforce-planning" target="_blank">Workforce Planning</a>).</li> </ul> <p><b>Testing notes</b>:</p> <ol> <li>Use the testing widget's <b>Try It!</b> option to test this endpoint.</li> <li>Use <b>Examples > Request Example</b> to see body parameters.</li> <li>Explore the response payload using the <b>Example</b> in the Response panel (human-readable and machine-format).</li> </ol>

post/people/{identifier}

Path parameters

identifierstring required

The backend-id of the Employee. Retrieve this ID from the database. <br> 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".<br> Alternaticely you can provide the employee's email address.

Request body

fieldsstring[]

An optional list of field IDs to return. Use dot notation as returned by <a href="https://apidocs.hibob.com/reference/get_company-people-fields" target="_blank">Fields metadata</a> (e.g. <code>root.id</code>, <code>work.department</code>). This is the canonical field ID. When not specified, a default set of fields and categories are returned including: <li>Basic employee fields like: name, id, avatar URL, creation date, etc.</li> <li>Basic categories:</li>

<ul> <li>About</li> </li>Employment</li> <li>Work</li> </ul> <br />Fields without service-user permission or with unknown IDs are silently omitted (200 OK). Response keys use slash notation (e.g. <code>/root/id</code>). See <a href="https://apidocs.hibob.com/docs/people-read-api-contract" target="_blank">People read API contract</a>. <br />The complete fields schema is described in the 200 response status section.
humanReadablestring

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. <br /><br />Flag values:<br /> <br> <b>If not sent:</b> will return only machine-format values. If you pass an invalid value it will be ignored and consdiered empty.<br> <br> Possible values: <br> <br> <b>APPEND</b> - include the additional "humanReadable" JSON node in the response. <br> <br> <b>REPLACE</b> - supply only humanReadable values in the JSON response instead of machine-readable values. <br>

Example request

{
  "fields": [
    "root.id",
    "root.firstName"
  ]
}

Response

Employee