---
title: "Search for employees"
method: POST
path: "/people/search"
tags: ["People"]
---

# Search for employees

`POST /people/search`

Search employee fields for many employees in one call. <p>See <b>Critical behaviors</b> below on this page for field IDs, filters, <code>showInactive</code>, permissions, no pagination, large-company batching, and integration limits. Full contract: <a href="https://apidocs.hibob.com/docs/people-read-api-contract" target="_blank">People read API contract</a>.</p> <p><b>Testing notes</b>:</p> <ol> <li>Use <b>Try It!</b> and <b>Examples &gt; Request Example</b> (default: active employees only; other examples cover terminated employees and batched reads by ID).</li> <li>Explore the response payload using the <b>Example</b> in the Response panel.</li> </ol>

## Request body

- ReadEmployeesRequestReference
  - `fields` string[] — Optional field IDs to return (max 400). 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>). Omit for the default field set. See <b>Critical behaviors</b> below on this page.
  - `filters` EmployeeFilter[] — Optional. One filter on <code>root.id</code> or <code>root.email</code> with operator <code>equals</code>. Omit when not filtering. See <b>Critical behaviors</b> below on this page.
    - `fieldPath` 'root.id' | 'root.email' — The field ID to filter by (dot notation, as returned by Fields metadata). Supported values: <code>root.id</code>, <code>root.email</code>. Any other field ID returns 400 HTTP error.
    - `operator` string — Supported operators: “equals” <br /> Any other operator will get a response of 400 HTTP error.
    - `values` string[] — The list of values to compare with the operator. An Empty list will result in 400 HTTP error.
  - `showInactive` boolean — Include inactive (typically terminated/former) employees. Default <code>false</code> (active only). See <b>Critical behaviors</b> below on this page.
  - `humanReadable` string — 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>

## Response `200`

Employees data response.

- Employees — Employee read response for <a href="https://apidocs.hibob.com/reference/post_people-search" target="_blank">Search for employees</a>. Contains <b>all</b> matching employees for the request in one <code>employees</code> array (not split across pages). Machine-format field values use slash-notation keys (e.g. <code>/root/id</code>) with a <code>value</code> property. The same employee object may also include nested category objects (e.g. <code>work.siteId</code>). Request field IDs use dot notation from metadata (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>.
  - `employees` union[] — All employees matching the search request and service user scope for this call.
    - union
      - EmployeeResponseReadable
        - `fullName` string — The full name of the Employee (first name + surname).
        - `displayName` string — Employee's display name. This defaults to first name & last name but can be customized.
        - `creationDateTime` string — The full timestamp of creation of the Employee.
        - `work` WorkPartReadable
          - `shortStartDate` string, date — The employee's employment start date without the year
          - `startDate` string, date — The employee's employment start date without the year
          - `manager` string — The full name of the employee's manager.
          - `tenureDuration` string — The tenure duration of the employee.
          - `durationOfEmployment` string — The tenure duration of the employee.
          - `reportsToIdInCompany` string — The ID in company of the manager.
          - `employeeIdInCompany` string — The ID of the manager.
          - `reportsTo` string — The full name of the person the employee reports to.
          - `tenureDurationYears` string — The tenture duration in years.
          - `department` string — The department this employee belong to.
          - `siteID` string — The ID of the site the employee belongs to.
          - `tenureYears` string — The tenture in years.
          - `isManager` string — Is the employee a manager (Yes/No).
          - `title` string — The employee's title.
          - `site` string — The employee's site.
          - `originalStartDate` string — The original date the employee started to work
          - `activeEffectiveDate` string — The active effective date the employee started to work
          - `secondLevelManager` string — The full name of the manager in the second level
          - `daysOfPreviousService` string — The number of days in previous service
          - `yearsOfService` string — The number of years in service
        - `avatarUrl` string — The URL of the source of the avatar image.
        - `secondName` string — Employee's surname.
        - `about` AboutPartReadable
          - `foodPreferences` string — Employee's food preferences.
          - `superpowers` string — Employee's super powers.
          - `hobbies` string — A list of the employee's hobbies.
          - `about` string — Employee's about sentence.
          - `avatar` string — Image URL of the employee's avatar.
        - `companyId` string — The ID of the employee's company.
        - `email` string, email — Employee's email address.
        - `surname` string — Employee's surname.
        - `coverImageUrl` string — The URL of the cover image.
        - `id` string — A unique identifier representing a specific employee.
        - `firstName` string — Employee's first name.
      - EmployeeResponseMachineFormat
        - `fullName` string — The full name of the Employee (first name + surname).
        - `/work/indirectReports` string[] — The internal IDs of the people the Employee reports to indirectly.
        - `/about/avatar` object — The avatar URL of the employee.
          - `value` string
        - `/work/reportsTo/email` object — The email of the person the employee reports to.
          - `value` string
        - `displayName` string — Employee's display name. This defaults to first name & last name but can be customized.
        - `/root/firstName` object — The first name of the employee.
          - `value` string
        - `/work/employeeIdInCompany` object — The internal ID of the employee.
          - `value` number
        - `/work/tenureDurationYears` object — The tenure duration in exact years of the employee.
          - `value` number
        - `/about/foodPreferences` object — The food preferences of the employee.
          - `value` string
        - `/work/site` object — The site name of the employee.
          - `value` string
        - `/work/tenureYears` object — The tenure duration in years of the employee (rounded value).
          - `value` string
        - `creationDateTime` string — The full timestamp of creation of the Employee.
        - `hobbies` object
          - `value` string[] — An array of the employee's hobbies.
        - `/root/email` object — The employee's email.
          - `value` string
        - `/work/title` object — The employee's title.
          - `value` string
        - `employee` object
          - `payrollManager` string
          - `hrbp` string
          - `itAdmin` string
          - `buddy` string
        - `work` object
          - `shortStartDate` string, date — The employee's employment start date without the year
          - `startDate` string, date — The employee's employment start date without the year
          - `manager` string — The full name of the employee's manager.
          - `tenureDuration` object — The tenure duration of the employee.
            - `periodISO` string
            - `sortFactor` number
            - `humanize` string
          - `custom` string[] — The custom fields of the employee.
          - `durationOfEmployment` object — The tenure duration of employment of the employee.
            - `periodISO` string
            - `sortFactor` number
            - `humanize` string
          - `reportsToIdInCompany` number — The ID in company of the manager.
          - `employeeIdInCompany` number — The ID of the manager.
          - `reportsTo` object — The full name of the person the employee reports to.
            - `displayName` string
            - `email` string
            - `surname` string
            - `firstName` string
            - `id` string
          - `workMobile` string — The work mobile number.
          - `workPhone` string — The work phone number.
          - `indirectReports` number — The person this employee reports to indirectly.
          - `siteID` number — The ID of the site the employee belongs to.
          - `tenureDurationYears` number — The tenture duration in years.
          - `department` string — The department this employee belong to.
          - `tenureYears` number — The tenture in years.
          - `isManager` string — Is the employee a manager (Yes/No).
          - `title` string — The employee's title.
          - `site` string — The employee's site.
          - `originalStartDate` string — The original date the employee started to work
          - `activeEffectiveDate` string — The active effective date the employee started to work
          - `directReports` number — The internal ID of the person this employee reports to directly
          - `secondLevelManager` string — The ID of the manager in the second level
          - `daysOfPreviousService` number — The number of days in previous service
          - `yearsOfService` number — The number of years in service
        - `avatarUrl` string — The URL of the source of the avatar image.
        - `secondName` string — Employee's surname.
        - `about` object
          - `foodPreferences` string[] — Employee's food preferences.
          - `socialData` object — Employee's social data.
            - `linkedin` string
            - `twitter` string
            - `facebook` string
          - `superpowers` string[] — Employee's super powers.
          - `hobbies` string[] — A list of the employee's hobbies.
          - `about` string — Employee's about sentence.
          - `avatar` string — Image URL of the employee's avatar.
        - `/root/fullName` object — The employee's full name.
          - `value` string
        - `companyId` number — The ID of the employee's company.
        - `/root/coverImageUrl` object — The employee's cover image.
          - `value` string
        - `/work/secondLevelManager` object — The ID of the second level manager of the employee.
          - `value` string
        - `/work/directReports` object — The number of people the employee reports to directly.
          - `value` number
        - `/work/yearsOfService` object — The number of years the employee has been in service.
          - `value` number
        - `/work/daysOfPreviousService` object — The number of years the employee has been in service previously.
          - `value` number
        - `/about/about` object — Employee's about sentence.
          - `value` string
        - `/root/avatarUrl` object — The url for the avatar file of the employee.
          - `value` string
        - `/work/shortStartDate` object — The start date of the employee in a short format (without the year).
          - `value` string
        - `/work/activeEffectiveDate` object — The date the employee bacame active.
          - `value` string
        - `/root/id` object — The ID of the employee.
          - `value` string
        - `email` string, email — Employee's email address.
        - `/work/manager` object — The ID of the employee's manager.
          - `value` string
        - `surname` string — Employee's surname.
        - `/work/reportsTo` object — The details of the person the employee reports to.
          - `value` object
            - `displayName` string
            - `email` string
            - `surname` string
            - `firstName` string
            - `id` string
        - `/root/companyId` object — The ID of the employee's company.
          - `value` number
        - `/root/displayName` object — The display name of the employee.
          - `value` string
        - `/work/department` object — The department of the employee.
          - `value` string
        - `/work/isManager` object — The department of the employee.
          - `value` boolean
        - `/work/originalStartDate` object — The original date the employee started work.
          - `value` string
        - `coverImageUrl` string — The URL of the cover image.
        - `/work/reportsToIdInCompany` object — The ID of the person this employee reports to.
          - `value` number
        - `/work/tenureDuration` object — The tenture duration of the employee.
          - `value` object
            - `periodISO` string
            - `sortFactor` number
            - `humanize` string
        - `/about/superpowers` object — The super powers of the employee.
          - `value` string[]
        - `id` string — A unique identifier representing a specific employee.
        - `firstName` string — Employee's first name.
        - `/work/siteId` object — The site ID of the employee's site.
          - `value` number
        - `/work/durationOfEmployment` object — The duration of the employee's employment.
          - `value` object
            - `periodISO` string
            - `sortFactor` number
            - `humanize` string

## Other 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 <a href="https://apidocs.hibob.com/docs/rate-limit" target="_blank">Rate Limiting</a>.
- `default` — Unexpected error.

---

[API](https://skmtc.net/hibob/apis/employee-data-api.md) · [All operations](https://skmtc.net/hibob/apis/employee-data-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/hibob/employee-data-api/revisions/0781ebbdda91/schema)