--- updatedAt: 2026-06-16T13:12:44.000Z --- Fetch the complete documentation index at: https://apidocs.hibob.com/llms.txt. Use this file to discover all available pages before exploring further. # Search for employees Search employee fields for many employees in one call.

See Critical behaviors below on this page for field IDs, filters, showInactive, permissions, no pagination, large-company batching, and integration limits. Full contract: People read API contract.

Testing notes:

  1. Use Try It! and Examples > Request Example (default: active employees only; other examples cover terminated employees and batched reads by ID).
  2. Explore the response payload using the Example in the Response panel.
## Critical behaviors Read the full [**People read API contract**](/docs/people-read-api-contract) before integrating. See also [**People API**](/reference/people) (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](/docs/people-read-api-contract#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](/docs/people-read-api-contract#read-after-update-consistency). ### Field IDs and responses * **Request field IDs** — Use **dot notation** from [Fields metadata](/reference/get_company-people-fields) (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)](/docs/fields-metadata#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](/docs/how-to-read-employee-data-tutorial#how-to-read-the-employee-status) and [showInactive (contract)](/docs/people-read-api-contract#showinactive-terminated-and-former-employees). ### 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](/docs/people-read-api-contract#recommended-pattern-for-large-companies-client-side-batching). ### 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](/reference/employee-tables) rows or [Workforce Planning](/reference/workforce-planning) positions. ### Request examples (Try It) Use **Examples → Request Example** on this page: | Example | Purpose | | :------------------------------------------ | :----------------------------------------------------------- | | **Default search** | `showInactive: false`, common fields — active employees only | | **Discover employee IDs** | Lightweight `root.id` only | | **Include terminated / inactive employees** | `showInactive: true` | | **Batch read by employee IDs** | `root.id` filter with multiple IDs | Default Try It body omits `filters` when not filtering. **Setup walkthrough:** [Read employee data](/docs/how-to-read-employee-data) · **Field types & **`humanReadable`**:** [Fields metadata](/docs/fields-metadata) # OpenAPI definition ```json { "openapi": "3.1.1", "info": { "title": "Employee data API", "description": "Access your employees data with the Public API", "license": { "name": "Proprietary", "url": "https://apidocs.hibob.com/docs/api-terms-of-use" }, "contact": { "name": "Hi Bob, Inc." }, "version": "1.0.0" }, "servers": [ { "url": "https://api.hibob.com/v1", "description": "Production" }, { "url": "https://api.sandbox.hibob.com/v1", "description": "Sandbox" } ], "x-readme": { "metrics-enabled": false }, "tags": [ { "name": "People", "description": "Operations for managing people and employee records" }, { "name": "Employee data Webhooks", "description": "Webhook events for employee and table entry operations" } ], "webhooks": { "employeeCreated": { "post": { "operationId": "post_webhook_employee-created", "tags": [ "Employee data Webhooks" ], "summary": "Employee created", "description": "Triggered when an employee is created.\n\nIn the right panel, open **Examples** and select **Payload Example** to see a real payload.\n", "parameters": [ { "name": "bob-signature", "in": "header", "required": true, "description": "Base64-encoded signature sent with each webhook request. Use it to verify that the request came from Bob. To verify webhook authenticity, see How does Bob calculate the signature.", "schema": { "type": "string", "example": "EQScIBkAtTKFW0ictgt5zzOsqIc2+xGEsM88jOdLuW4CM/a3gLEfrKV+IC5IHx0xbirzLKPIfaZjCGwzuiyI8w==" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeCreatedEvent" }, "example": { "companyId": 637323, "type": "employee.created", "triggeredBy": "3332883804594373380", "triggeredAt": "2024-12-26T11:29:14.399997", "version": "v2", "data": { "employeeId": "3332883894235038486" } } } } }, "responses": { "200": { "description": "Webhook received successfully" }, "400": { "description": "Invalid webhook payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "employeeUpdated": { "post": { "operationId": "post_webhook_employee-updated", "tags": [ "Employee data Webhooks" ], "summary": "Employee updated", "description": "Triggered when an employee's field is updated.\n\nThe payload includes only the fields that were explicitly changed. Calculated\nfields affected by an update (e.g., age when birthDate changes) are not included.\n\nThis event is also sent when a table entry create or update causes employee-level fields to change; the payload then contains the affected field IDs in fieldUpdates. Bank accounts and custom tables do not trigger this event when their entries change.\n\nIn the right panel, open **Examples** and select **Payload Example** to see a real payload.\n", "parameters": [ { "name": "bob-signature", "in": "header", "required": true, "description": "Base64-encoded signature sent with each webhook request. Use it to verify that the request came from Bob. To verify webhook authenticity, see How does Bob calculate the signature.", "schema": { "type": "string", "example": "EQScIBkAtTKFW0ictgt5zzOsqIc2+xGEsM88jOdLuW4CM/a3gLEfrKV+IC5IHx0xbirzLKPIfaZjCGwzuiyI8w==" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeUpdatedEvent" }, "examples": { "profileField": { "summary": "Profile field change", "value": { "companyId": 637323, "type": "employee.updated", "triggeredBy": "3332883804594373380", "triggeredAt": "2024-12-26T11:29:14.399997", "version": "v2", "data": { "employeeId": "3332883894235038486", "fieldUpdates": [ { "id": "personal.birthDate" } ] } } }, "afterLifecycleTable": { "summary": "After lifecycle table change", "value": { "companyId": 636192, "type": "employee.updated", "triggeredBy": "3332883804594373380", "triggeredAt": "2025-01-08T13:06:26.893941", "version": "v2", "data": { "employeeId": "3332883854254932743", "fieldUpdates": [ { "id": "employee.recentLeaveStartDate" }, { "id": "internal.status" }, { "id": "employee.recentLeaveEndDate" }, { "id": "internal.lifecycleStatus" } ] } } }, "afterWorkTable": { "summary": "After work table change", "value": { "companyId": 636192, "type": "employee.updated", "triggeredBy": "3332883804594373380", "triggeredAt": "2025-01-08T13:28:55.545382", "version": "v2", "data": { "employeeId": "3332883904477528858", "fieldUpdates": [ { "id": "work.department" }, { "id": "work.title" }, { "id": "work.activeEffectiveDate" } ] } } }, "afterEmploymentTable": { "summary": "After employment table change", "value": { "companyId": 636192, "type": "employee.updated", "triggeredBy": "3332883804594373380", "triggeredAt": "2025-01-08T13:51:59.905057", "version": "v2", "data": { "employeeId": "3332883904477528858", "fieldUpdates": [ { "id": "payroll.employment.type" } ] } } }, "afterSalaryTable": { "summary": "After salary table change", "value": { "companyId": 636192, "type": "employee.updated", "triggeredBy": "3332883804594373380", "triggeredAt": "2026-03-02T12:17:21.974884", "version": "v2", "data": { "employeeId": "3460447757808959739", "fieldUpdates": [ { "id": "payroll.salary.activeEffectiveDate" }, { "id": "payroll.salary.payPeriod" }, { "id": "payroll.salary.monthlyPayment" }, { "id": "payroll.salary.yearlyPayment" }, { "id": "payroll.salary.payment" }, { "id": "payroll.salary.payFrequency" } ] } } }, "afterAddressTable": { "summary": "After address table change", "value": { "companyId": 636192, "type": "employee.updated", "triggeredBy": "3332883804594373380", "triggeredAt": "2026-03-02T12:19:35.027449", "version": "v2", "data": { "employeeId": "3460447757808959739", "fieldUpdates": [ { "id": "address.postCode" }, { "id": "address.country" } ] } } }, "afterVariablePayTable": { "summary": "After variable pay table change", "value": { "companyId": 636192, "type": "employee.updated", "triggeredBy": "3332883804594373380", "triggeredAt": "2026-03-02T12:16:38.725127", "version": "v2", "data": { "employeeId": "3460447757808959739", "fieldUpdates": [ { "id": "payroll.variable.Executive bonus.amount" }, { "id": "payroll.variable.Bonus.paymentPeriod" }, { "id": "payroll.variable.Bonus.amount" }, { "id": "payroll.variable.Bonus.payoutType" }, { "id": "payroll.variable.Executive bonus.payoutType" }, { "id": "payroll.variable.Executive bonus.paymentPeriod" } ] } } }, "afterEntitlementTable": { "summary": "After entitlement table change", "value": { "companyId": 636192, "type": "employee.updated", "triggeredBy": "3332883804594373380", "triggeredAt": "2026-03-02T12:15:08.446777", "version": "v2", "data": { "employeeId": "3460447757808959739", "fieldUpdates": [ { "id": "payroll.entitlement.Season ticket loans.amount" }, { "id": "payroll.entitlement.Childcare vouchers.amount" } ] } } } } } } }, "responses": { "200": { "description": "Webhook received successfully" }, "400": { "description": "Invalid webhook payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "employeeDeleted": { "post": { "operationId": "post_webhook_employee-deleted", "tags": [ "Employee data Webhooks" ], "summary": "Employee deleted", "description": "Triggered when an employee is deleted.\n\nThe payload includes the employee email so you can retain a reference to the\ndeleted employee after their record is no longer accessible.\n\nIn the right panel, open **Examples** and select **Payload Example** to see a real payload.\n", "parameters": [ { "name": "bob-signature", "in": "header", "required": true, "description": "Base64-encoded signature sent with each webhook request. Use it to verify that the request came from Bob. To verify webhook authenticity, see How does Bob calculate the signature.", "schema": { "type": "string", "example": "EQScIBkAtTKFW0ictgt5zzOsqIc2+xGEsM88jOdLuW4CM/a3gLEfrKV+IC5IHx0xbirzLKPIfaZjCGwzuiyI8w==" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeDeletedEvent" }, "example": { "companyId": 639814, "type": "employee.deleted", "triggeredBy": "3647561042940134248", "triggeredAt": "2025-08-11T08:02:39.118536", "version": "v2", "data": { "employeeId": "3647561274138559361", "email": "zoe.clark_639814@samplebob.com" } } } } }, "responses": { "200": { "description": "Webhook received successfully" }, "400": { "description": "Invalid webhook payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "employeeJoined": { "post": { "operationId": "post_webhook_employee-joined", "tags": [ "Employee data Webhooks" ], "summary": "Employee joined", "description": "Triggered when an employee is granted access, once the corresponding\nlifecycle entry becomes effective.\n\nLifecycle events are triggered automatically at midnight on the effective\ndate of the lifecycle table entry (according to the site's timezone).\n\nIn the right panel, open **Examples** and select **Payload Example** to see a real payload.\n", "parameters": [ { "name": "bob-signature", "in": "header", "required": true, "description": "Base64-encoded signature sent with each webhook request. Use it to verify that the request came from Bob. To verify webhook authenticity, see How does Bob calculate the signature.", "schema": { "type": "string", "example": "EQScIBkAtTKFW0ictgt5zzOsqIc2+xGEsM88jOdLuW4CM/a3gLEfrKV+IC5IHx0xbirzLKPIfaZjCGwzuiyI8w==" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeJoinedEvent" }, "example": { "companyId": 637323, "type": "employee.joined", "triggeredBy": "3332883804594373380", "triggeredAt": "2024-12-26T11:29:14.399997", "version": "v2", "data": { "employeeId": "3332883894235038486" } } } } }, "responses": { "200": { "description": "Webhook received successfully" }, "400": { "description": "Invalid webhook payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "employeeLeft": { "post": { "operationId": "post_webhook_employee-left", "tags": [ "Employee data Webhooks" ], "summary": "Employee terminated", "description": "Triggered when an employee is set as terminated or on Garden leave\n(whichever occurs first), once the corresponding lifecycle entry becomes effective.\n\nLifecycle events are triggered automatically at midnight on the effective\ndate of the lifecycle table entry (according to the site's timezone).\n\nIn the right panel, open **Examples** and select **Payload Example** to see a real payload.\n", "parameters": [ { "name": "bob-signature", "in": "header", "required": true, "description": "Base64-encoded signature sent with each webhook request. Use it to verify that the request came from Bob. To verify webhook authenticity, see How does Bob calculate the signature.", "schema": { "type": "string", "example": "EQScIBkAtTKFW0ictgt5zzOsqIc2+xGEsM88jOdLuW4CM/a3gLEfrKV+IC5IHx0xbirzLKPIfaZjCGwzuiyI8w==" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeLeftEvent" }, "example": { "companyId": 637323, "type": "employee.left", "triggeredBy": "3332883804594373380", "triggeredAt": "2024-12-26T11:29:14.399997", "version": "v2", "data": { "employeeId": "3332883894235038486" } } } } }, "responses": { "200": { "description": "Webhook received successfully" }, "400": { "description": "Invalid webhook payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "employeeActivated": { "post": { "operationId": "post_webhook_employee-activated", "tags": [ "Employee data Webhooks" ], "summary": "Employee activated", "description": "Triggered when an employee's access is enabled, once the corresponding\nlifecycle entry becomes effective.\n\nIn the right panel, open **Examples** and select **Payload Example** to see a real payload.\n", "parameters": [ { "name": "bob-signature", "in": "header", "required": true, "description": "Base64-encoded signature sent with each webhook request. Use it to verify that the request came from Bob. To verify webhook authenticity, see How does Bob calculate the signature.", "schema": { "type": "string", "example": "EQScIBkAtTKFW0ictgt5zzOsqIc2+xGEsM88jOdLuW4CM/a3gLEfrKV+IC5IHx0xbirzLKPIfaZjCGwzuiyI8w==" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeActivatedEvent" }, "example": { "companyId": 636192, "type": "employee.activated", "triggeredBy": "3332883804594373380", "triggeredAt": "2025-01-08T13:06:26.935613", "version": "v2", "data": { "employeeId": "3332883854254932743" } } } } }, "responses": { "200": { "description": "Webhook received successfully" }, "400": { "description": "Invalid webhook payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "employeeInactivated": { "post": { "operationId": "post_webhook_employee-inactivated", "tags": [ "Employee data Webhooks" ], "summary": "Employee inactivated", "description": "Triggered when an employee is set to be on leave or terminated, once the\ncorresponding lifecycle entry becomes effective.\n\nThis event is not triggered if **Remain active** is selected when putting\nthe employee on leave.\n\nIn the right panel, open **Examples** and select **Payload Example** to see a real payload.\n", "parameters": [ { "name": "bob-signature", "in": "header", "required": true, "description": "Base64-encoded signature sent with each webhook request. Use it to verify that the request came from Bob. To verify webhook authenticity, see How does Bob calculate the signature.", "schema": { "type": "string", "example": "EQScIBkAtTKFW0ictgt5zzOsqIc2+xGEsM88jOdLuW4CM/a3gLEfrKV+IC5IHx0xbirzLKPIfaZjCGwzuiyI8w==" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeInactivatedEvent" }, "example": { "companyId": 636192, "type": "employee.inactivated", "triggeredBy": "3332883804594373380", "triggeredAt": "2025-01-08T13:06:26.915964", "version": "v2", "data": { "employeeId": "3332883854254932743" } } } } }, "responses": { "200": { "description": "Webhook received successfully" }, "400": { "description": "Invalid webhook payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "employeeTemporaryLeave": { "post": { "operationId": "post_webhook_employee-temporary-leave", "tags": [ "Employee data Webhooks" ], "summary": "Employee on temporary leave", "description": "Triggered when an employee is set to be on temporary leave, once the\ncorresponding lifecycle entry becomes effective.\n\nThis event is not triggered if **Remain active** is selected when putting\nthe employee on leave.\n\nIn the right panel, open **Examples** and select **Payload Example** to see a real payload.\n", "parameters": [ { "name": "bob-signature", "in": "header", "required": true, "description": "Base64-encoded signature sent with each webhook request. Use it to verify that the request came from Bob. To verify webhook authenticity, see How does Bob calculate the signature.", "schema": { "type": "string", "example": "EQScIBkAtTKFW0ictgt5zzOsqIc2+xGEsM88jOdLuW4CM/a3gLEfrKV+IC5IHx0xbirzLKPIfaZjCGwzuiyI8w==" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeTemporaryLeaveEvent" }, "example": { "companyId": 636192, "type": "employee.temporaryLeave", "triggeredBy": "3332883804594373380", "triggeredAt": "2025-01-08T13:06:26.935613", "version": "v2", "data": { "employeeId": "3332883854254932743" } } } } }, "responses": { "200": { "description": "Webhook received successfully" }, "400": { "description": "Invalid webhook payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "tableEntryCreated": { "post": { "operationId": "post_webhook_table-entry-created", "tags": [ "Employee data Webhooks" ], "summary": "Table entry created", "description": "Triggered when an entry is added to an employee's table (including\nout-of-the-box and custom tables).\n\nDoes not apply to Training, Equity, Positions, or Jobs tables.\n\nTo identify the row/entry when fetching using the API, use the property that appears in the payload for that table type:\n\n- **id** — Included only for non-historical tables (e.g. custom tables, bank accounts). Identifies the entry row. Omitted for historical tables.\n- **effectiveDate** — Included only for historical tables. Identifies the entry row for that table type. Omitted for non-historical tables.\n\nEach event includes exactly one of `effectiveDate` or `id` inside `data`, depending on whether the table is historical.\n\nTo learn more about table types, see Employee data modeling.\n\nWhen a table entry is created or updated, it may also update employee-level fields (e.g. derived or linked). In that case you will also receive an employee.updated event with the list of changed field IDs in fieldUpdates. Bank accounts and custom tables do not trigger this additional employee.updated event.\n\nIn the right panel, open **Examples** and select **Payload Example** to see a real payload.\n", "parameters": [ { "name": "bob-signature", "in": "header", "required": true, "description": "Base64-encoded signature sent with each webhook request. Use it to verify that the request came from Bob. To verify webhook authenticity, see How does Bob calculate the signature.", "schema": { "type": "string", "example": "EQScIBkAtTKFW0ictgt5zzOsqIc2+xGEsM88jOdLuW4CM/a3gLEfrKV+IC5IHx0xbirzLKPIfaZjCGwzuiyI8w==" } }, { "name": "get-table", "in": "header", "required": false, "description": "**Present only for custom tables.** The URL to call to read this table entry. For out-of-the-box tables the path is well known, but for custom tables this header provides the full URL with the table ID (e.g. `category_1716214820047__table_1716214839517`) already in the right place. Example: `https://api.hibob.com/v1/people/custom-tables/{employeeId}/{custom_table_id}`.", "schema": { "type": "string", "example": "https://api.hibob.com/v1/people/custom-tables/3332883884017713938/category_1716214820047__table_1716214839517" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TableEntryCreatedEvent" }, "examples": { "lifecycle": { "summary": "Lifecycle", "value": { "companyId": 636192, "type": "table.entry.created", "triggeredBy": "3332883804594373380", "triggeredAt": "2025-01-08T13:06:26.915906", "version": "v2", "data": { "employeeId": "3332883854254932743", "tableId": "lifecycle", "effectiveDate": "2025-01-08" } } }, "work": { "summary": "Work", "value": { "companyId": 636192, "type": "table.entry.created", "triggeredBy": "3332883804594373380", "triggeredAt": "2025-01-08T13:28:55.561963", "version": "v2", "data": { "employeeId": "3332883904477528858", "tableId": "work", "effectiveDate": "2024-09-02" } } }, "employment": { "summary": "Employment", "value": { "companyId": 636192, "type": "table.entry.created", "triggeredBy": "3332883804594373380", "triggeredAt": "2025-01-08T13:30:41.592528", "version": "v2", "data": { "employeeId": "3332883904477528858", "tableId": "employment", "effectiveDate": "2025-01-08" } } }, "bankAccounts": { "summary": "Bank accounts", "value": { "companyId": 636192, "type": "table.entry.created", "triggeredBy": "3332883804594373380", "triggeredAt": "2025-01-08T13:54:03.608759", "version": "v2", "data": { "employeeId": "3332883904477528858", "tableId": "bankAccounts", "id": 6236350 } } }, "salary": { "summary": "Payroll (salary)", "value": { "companyId": 636192, "type": "table.entry.created", "triggeredBy": "3332883804594373380", "triggeredAt": "2025-01-08T13:55:00.000000", "version": "v2", "data": { "employeeId": "3332883904477528858", "tableId": "salary", "effectiveDate": "2025-01-08" } } }, "customTable": { "summary": "Custom table", "value": { "companyId": 636192, "type": "table.entry.created", "triggeredBy": "3332883804594373380", "triggeredAt": "2026-03-02T12:21:30.000000", "version": "v2", "data": { "employeeId": "3460447757808959739", "tableId": "category_1716214820047__table_1716214839517", "id": 11542446 } } }, "address": { "summary": "Address", "value": { "companyId": 636192, "type": "table.entry.created", "triggeredBy": "3332883804594373380", "triggeredAt": "2026-03-02T12:19:34.000000", "version": "v2", "data": { "employeeId": "3460447757808959739", "tableId": "address", "effectiveDate": "2026-03-02" } } }, "variablePay": { "summary": "Variable Pay", "value": { "companyId": 636192, "type": "table.entry.created", "triggeredBy": "3332883804594373380", "triggeredAt": "2026-03-02T12:16:37.000000", "version": "v2", "data": { "employeeId": "3460447757808959739", "tableId": "variable", "effectiveDate": "2026-03-02" } } }, "entitlement": { "summary": "Entitlement", "value": { "companyId": 636192, "type": "table.entry.created", "triggeredBy": "3332883804594373380", "triggeredAt": "2026-03-02T12:15:07.000000", "version": "v2", "data": { "employeeId": "3460447757808959739", "tableId": "entitlement", "effectiveDate": "2026-03-03" } } }, "deduction": { "summary": "Deduction", "value": { "companyId": 636192, "type": "table.entry.created", "triggeredBy": "3332883804594373380", "triggeredAt": "2026-03-02T12:13:18.445371", "version": "v2", "data": { "employeeId": "3460447757808959739", "tableId": "deduction", "effectiveDate": "2026-03-02" } } } } } } }, "responses": { "200": { "description": "Webhook received successfully" }, "400": { "description": "Invalid webhook payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "tableEntryUpdated": { "post": { "operationId": "post_webhook_table-entry-updated", "tags": [ "Employee data Webhooks" ], "summary": "Table entry updated", "description": "Triggered when an entry is updated in an employee's table (including\nout-of-the-box and custom tables).\n\nDoes not apply to Training, Equity, Positions, or Jobs tables.\n\nTo identify the row/entry when fetching using the API, use the property that appears in the payload for that table type:\n\n- **id** — Included only for non-historical tables (e.g. custom tables, bank accounts). Identifies the entry row. Omitted for historical tables.\n- **effectiveDate** — Included only for historical tables. Identifies the entry row for that table type. Omitted for non-historical tables.\n\nEach event includes exactly one of `effectiveDate` or `id` inside `data`, depending on whether the table is historical.\n\nTo learn more about table types, see Employee data modeling.\n\nWhen a table entry is created or updated, it may also update employee-level fields (e.g. derived or linked). In that case you will also receive an employee.updated event with the list of changed field IDs in fieldUpdates. Bank accounts and custom tables do not trigger this additional employee.updated event.\n\nIn the right panel, open **Examples** and select **Payload Example** to see a real payload.\n", "parameters": [ { "name": "bob-signature", "in": "header", "required": true, "description": "Base64-encoded signature sent with each webhook request. Use it to verify that the request came from Bob. To verify webhook authenticity, see How does Bob calculate the signature.", "schema": { "type": "string", "example": "EQScIBkAtTKFW0ictgt5zzOsqIc2+xGEsM88jOdLuW4CM/a3gLEfrKV+IC5IHx0xbirzLKPIfaZjCGwzuiyI8w==" } }, { "name": "get-table", "in": "header", "required": false, "description": "**Present only for custom tables.** The URL to call to read this table entry. For out-of-the-box tables the path is well known, but for custom tables this header provides the full URL with the table ID (e.g. `category_1716214820047__table_1716214839517`) already in the right place. Example: `https://api.hibob.com/v1/people/custom-tables/{employeeId}/{custom_table_id}`.", "schema": { "type": "string", "example": "https://api.hibob.com/v1/people/custom-tables/3332883884017713938/category_1716214820047__table_1716214839517" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TableEntryUpdatedEvent" }, "examples": { "lifecycle": { "summary": "Lifecycle", "value": { "companyId": 636192, "type": "table.entry.updated", "triggeredBy": "3332883804594373380", "triggeredAt": "2025-01-08T13:06:27.000000", "version": "v2", "data": { "employeeId": "3332883854254932743", "tableId": "lifecycle", "effectiveDate": "2025-01-08" } } }, "work": { "summary": "Work", "value": { "companyId": 636192, "type": "table.entry.updated", "triggeredBy": "3332883804594373380", "triggeredAt": "2025-01-08T13:28:05.816304", "version": "v2", "data": { "employeeId": "3332883904477528858", "tableId": "work", "effectiveDate": "2024-03-27" } } }, "employment": { "summary": "Employment", "value": { "companyId": 636192, "type": "table.entry.updated", "triggeredBy": "3332883804594373380", "triggeredAt": "2025-01-08T13:51:00.000000", "version": "v2", "data": { "employeeId": "3332883904477528858", "tableId": "employment", "effectiveDate": "2025-01-08" } } }, "salary": { "summary": "Payroll (salary)", "value": { "companyId": 636192, "type": "table.entry.updated", "triggeredBy": "3332883804594373380", "triggeredAt": "2025-01-08T13:55:45.055159", "version": "v2", "data": { "employeeId": "3332883904477528858", "tableId": "salary", "effectiveDate": "2015-03-03" } } }, "bankAccounts": { "summary": "Bank accounts", "value": { "companyId": 636192, "type": "table.entry.updated", "triggeredBy": "3332883804594373380", "triggeredAt": "2025-01-08T13:54:10.000000", "version": "v2", "data": { "employeeId": "3332883904477528858", "tableId": "bankAccounts", "id": 6236350 } } }, "customTable": { "summary": "Custom table", "value": { "companyId": 636192, "type": "table.entry.updated", "triggeredBy": "3332883804594373380", "triggeredAt": "2026-03-02T12:21:31.349254", "version": "v2", "data": { "employeeId": "3460447757808959739", "tableId": "category_1716214820047__table_1716214839517", "id": 11542446 } } }, "address": { "summary": "Address", "value": { "companyId": 636192, "type": "table.entry.updated", "triggeredBy": "3332883804594373380", "triggeredAt": "2026-03-02T12:19:35.027449", "version": "v2", "data": { "employeeId": "3460447757808959739", "tableId": "address", "effectiveDate": "2026-03-02" } } }, "variablePay": { "summary": "Variable Pay", "value": { "companyId": 636192, "type": "table.entry.updated", "triggeredBy": "3332883804594373380", "triggeredAt": "2026-03-02T12:16:38.749797", "version": "v2", "data": { "employeeId": "3460447757808959739", "tableId": "variable", "effectiveDate": "2026-03-02" } } }, "entitlement": { "summary": "Entitlement", "value": { "companyId": 636192, "type": "table.entry.updated", "triggeredBy": "3332883804594373380", "triggeredAt": "2026-03-02T12:15:08.471303", "version": "v2", "data": { "employeeId": "3460447757808959739", "tableId": "entitlement", "effectiveDate": "2026-03-03" } } }, "deduction": { "summary": "Deduction", "value": { "companyId": 636192, "type": "table.entry.updated", "triggeredBy": "3332883804594373380", "triggeredAt": "2026-03-02T12:13:20.000000", "version": "v2", "data": { "employeeId": "3460447757808959739", "tableId": "deduction", "effectiveDate": "2026-03-02" } } } } } } }, "responses": { "200": { "description": "Webhook received successfully" }, "400": { "description": "Invalid webhook payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } } }, "paths": { "/people/search": { "post": { "operationId": "post_people-search", "tags": [ "People" ], "summary": "Search for employees", "description": "Search employee fields for many employees in one call.

See Critical behaviors below on this page for field IDs, filters, showInactive, permissions, no pagination, large-company batching, and integration limits. Full contract: People read API contract.

Testing notes:

  1. Use Try It! and Examples > Request Example (default: active employees only; other examples cover terminated employees and batched reads by ID).
  2. Explore the response payload using the Example in the Response panel.
", "requestBody": { "description": "Select fields and options. See Critical behaviors below. Use Request Example for sample bodies (omit filters when not filtering).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadEmployeesRequestReference" }, "examples": { "defaultSearch": { "summary": "Default search (active employees only)", "description": "Default Try It example. See Critical behaviors below.", "value": { "fields": [ "root.id", "root.firstName" ], "showInactive": false, "filters": [ { "fieldPath": "root.id", "operator": "equals", "values": [ "3332883884017713938", "3332883909410030364" ] } ] } }, "discoverEmployeeIds": { "summary": "Discover employee IDs (lightweight)", "description": "ID discovery only. See Critical behaviors below.", "value": { "fields": [ "root.id" ], "showInactive": false } }, "includeTerminatedEmployees": { "summary": "Include terminated / inactive employees", "description": "showInactive true. See Critical behaviors below.", "value": { "showInactive": true, "fields": [ "root.id", "internal.status", "internal.lifecycleStatus" ] } }, "batchReadByEmployeeIds": { "summary": "Batch read by employee IDs", "description": "Batched root.id filter. See Critical behaviors below.", "value": { "fields": [ "root.id", "root.firstName", "work.department" ], "showInactive": false, "filters": [ { "fieldPath": "root.id", "operator": "equals", "values": [ "3332883884017713938", "3332883909410030364" ] } ] } } } } }, "required": true }, "responses": { "200": { "description": "Employees data response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Employees" }, "examples": { "EmployeeResponseReadableExample": { "summary": "human readable only (humanReadable=\"REPLACE\")", "value": { "employees": [ { "fullName": "example", "displayName": "example", "creationDateTime": "2024-03-27T09:12:21.680867", "work": { "shortStartDate": "01/05", "startDate": "01/05/2015", "manager": "example", "tenureDuration": "9 years, 1 month and 26 days", "durationOfEmployment": "9 years, 1 month and 26 days", "reportsToIdInCompany": "30", "employeeIdInCompany": "40", "reportsTo": "example", "tenureDurationYears": "9.155", "department": "example", "siteId": "example", "tenureYears": "9", "isManager": "No", "title": "example", "site": "example", "originalStartDate": "01/05/2015", "activeEffectiveDate": "01/05/2015", "secondLevelManager": "example", "daysOfPreviousService": "0", "yearsOfService": "9.155" }, "avatarUrl": "string URL", "secondName": "example", "about": { "foodPreferences": "", "superpowers": "example", "hobbies": "example", "about": "string", "avatar": "string URL" }, "companyId": "636192", "email": "example@samplebob.com", "surname": "example", "coverImageUrl": "string URL", "id": "3332883884017713938", "firstName": "example" } ] } }, "EmployeeResponseMachineFormatExample": { "summary": "Machine format only (humanReadable=\"\")", "value": { "employees": [ { "fullName": "example", "/work/indirectReports": { "value": 33 }, "/about/avatar": { "string URL": null }, "/work/reportsTo/email": { "value": "example@samplebob.com" }, "displayName": "example", "/root/firstName": { "value": "example" }, "/work/employeeIdInCompany": { "value": 39 }, "/work/tenureDurationYears": { "value": 9.273 }, "/about/foodPreferences": { "value": [ "vegan" ] }, "/work/site": { "value": "New York (Demo)" }, "/work/tenureYears": { "value": 9 }, "creationDateTime": "2024-03-27T09:12:25.002884", "/about/hobbies": { "value": [ "yoga", "cooking", "261314348" ] }, "/root/email": { "value": "example@samplebob.com" }, "/work/title": { "value": "Desigexamplener" }, "employee": { "payrollManager": null, "hrbp": null, "itAdmin": null, "buddy": null }, "work": { "shortStartDate": "03-20", "startDate": "2015-03-20", "manager": "3332883909410030364", "tenureDuration": { "periodISO": "P9Y3M8D", "sortFactor": 3338, "humanize": "9 years, 3 months and 8 days" }, "custom": { "field_1711886937296": null }, "durationOfEmployment": { "periodISO": "P9Y3M8D", "sortFactor": 3338, "humanize": "9 years, 3 months and 8 days" }, "reportsToIdInCompany": 1, "employeeIdInCompany": 39, "reportsTo": { "displayName": "Zoe Clark", "email": "zoe.clark_636192@samplebob.com", "surname": "Clark", "firstName": "Zoe", "id": "3332883909410030364" }, "indirectReports": 33, "siteId": 2510068, "tenureDurationYears": 9.273, "department": "Product", "tenureYears": 9, "isManager": true, "title": "example", "site": "example", "originalStartDate": "2015-03-20", "activeEffectiveDate": "2015-03-20", "directReports": 1, "secondLevelManager": "3332883848206746373", "daysOfPreviousService": 0, "yearsOfService": 9.273 }, "/root/creationDateTime": { "value": "2024-03-27T09:12:25.002884" }, "secondName": null, "avatarUrl": "string URL", "/work/startDate": { "value": "2015-03-20" }, "about": { "foodPreferences": [ "vegan" ], "socialData": { "linkedin": null, "twitter": null, "facebook": null }, "superpowers": [ "excel" ], "hobbies": [ "yoga", "cooking", "261314348" ], "about": "string", "avatar": "string URL" }, "/root/fullName": { "value": "example" }, "companyId": 636192, "/root/coverImageUrl": { "value": "string URL" }, "/work/secondLevelManager": { "value": "3332883848206746373" }, "/work/directReports": { "value": 1 }, "/work/yearsOfService": { "value": 9.273 }, "/work/daysOfPreviousService": { "value": 0 }, "/about/about": { "value": "string" }, "/root/avatarUrl": { "value": "string URL" }, "/root/surname": { "value": "example" }, "/work/shortStartDate": { "value": "03-20" }, "/work/activeEffectiveDate": { "value": "2015-03-20" }, "/root/id": { "value": "3332883911884669725" }, "email": "amy.miles_636192@samplebob.com", "/work/manager": { "value": "3332883909410030364" }, "surname": "Miles", "/work/reportsTo": { "value": { "displayName": "Zoe Clark", "email": "zoe.clark_636192@samplebob.com", "surname": "Clark", "firstName": "Zoe", "id": "3332883909410030364" } }, "/root/companyId": { "value": 636192 }, "/root/displayName": { "value": "example" }, "/work/department": { "value": "example" }, "/work/isManager": { "value": true }, "/work/originalStartDate": { "value": "2015-03-20" }, "coverImageUrl": "string URL", "/work/reportsToIdInCompany": { "value": 1 }, "/work/tenureDuration": { "value": { "periodISO": "P9Y3M8D", "sortFactor": 3338, "humanize": "9 years, 3 months and 8 days" } }, "/about/superpowers": { "value": [ "excel" ] }, "id": "3332883911884669725", "firstName": "Amy", "/work/siteId": { "value": 2510068 }, "/work/durationOfEmployment": { "value": { "periodISO": "P9Y3M8D", "sortFactor": 3338, "humanize": "9 years, 3 months and 8 days" } } } ] } } } } } }, "400": { "description": "Bad request. The request contains incorrect parameters or syntax errors. Please review the request body" }, "403": { "description": "Forbidden. The service user does not have permissions to access this table or employees. Check the permissions as explained in the endpoint description." }, "429": { "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." }, "default": { "description": "Unexpected error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "Basic": [] }, { "Bearer": [] } ] } } }, "components": { "schemas": { "WebhookEvent": { "type": "object", "description": "Base webhook event structure containing common webhook properties", "properties": { "companyId": { "type": "number", "description": "The company ID" }, "type": { "type": "string", "description": "The event type (e.g., employee.created)" }, "triggeredBy": { "type": "string", "description": "The backend-id of the employee that triggered the event, or 'system' for system-triggered events" }, "triggeredAt": { "type": "string", "description": "The timestamp when the event occurred (ISO 8601-style string)" }, "version": { "type": "string", "description": "The webhook version (e.g., v2)" }, "data": { "type": "object", "description": "Event-specific payload; structure varies by event type" } }, "required": [ "companyId", "type", "triggeredBy", "triggeredAt", "version", "data" ] }, "EmployeeCreatedEventData": { "type": "object", "description": "Data payload for employee.created event", "properties": { "employeeId": { "type": "string", "description": "The unique identifier of the employee" } }, "required": [ "employeeId" ] }, "EmployeeUpdatedEventData": { "type": "object", "description": "Data payload for employee.updated event", "properties": { "employeeId": { "type": "string", "description": "The unique identifier of the employee" }, "fieldUpdates": { "type": "array", "description": "The field IDs that were explicitly changed (calculated fields are not included)", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The field ID (e.g., personal.birthDate)" } } } } }, "required": [ "employeeId" ] }, "EmployeeDeletedEventData": { "type": "object", "description": "Data payload for employee.deleted event", "properties": { "employeeId": { "type": "string", "description": "The unique identifier of the deleted employee" }, "email": { "type": "string", "description": "The employee email (included since the record is no longer available after deletion)" } }, "required": [ "employeeId" ] }, "EmployeeLifecycleEventData": { "type": "object", "description": "Data payload for lifecycle events (joined, left, activated, inactivated, temporaryLeave)", "properties": { "employeeId": { "type": "string", "description": "The unique identifier of the employee" } }, "required": [ "employeeId" ] }, "TableEntryEventData": { "type": "object", "description": "Data payload for table.entry.created and table.entry.updated events. Historical tables include `effectiveDate` only; non-historical tables include numeric `id` only. The other identifier is omitted from the JSON when not applicable.", "properties": { "employeeId": { "type": "string", "description": "The unique identifier of the employee" }, "tableId": { "type": "string", "description": "The table identifier (e.g., lifecycle, work, employment, salary, bankAccounts)" }, "effectiveDate": { "type": "string", "format": "date", "description": "Present for historical tables only. The effective date that identifies this row together with employeeId. Omitted for non-historical tables." }, "id": { "type": "integer", "description": "Present for non-historical tables only. The numeric ID of this table row when reading via the API. Omitted for historical tables." } }, "required": [ "employeeId", "tableId" ], "oneOf": [ { "required": [ "effectiveDate" ] }, { "required": [ "id" ] } ] }, "EmployeeCreatedEvent": { "allOf": [ { "$ref": "#/components/schemas/WebhookEvent" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "employee.created" ], "description": "Event type for employee created" }, "data": { "$ref": "#/components/schemas/EmployeeCreatedEventData" } } } ] }, "EmployeeUpdatedEvent": { "allOf": [ { "$ref": "#/components/schemas/WebhookEvent" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "employee.updated" ], "description": "Event type for employee field updated" }, "data": { "$ref": "#/components/schemas/EmployeeUpdatedEventData" } } } ] }, "EmployeeDeletedEvent": { "allOf": [ { "$ref": "#/components/schemas/WebhookEvent" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "employee.deleted" ], "description": "Event type for employee deleted" }, "data": { "$ref": "#/components/schemas/EmployeeDeletedEventData" } } } ] }, "EmployeeJoinedEvent": { "allOf": [ { "$ref": "#/components/schemas/WebhookEvent" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "employee.joined" ], "description": "Event type for employee joined (access granted)" }, "data": { "$ref": "#/components/schemas/EmployeeLifecycleEventData" } } } ] }, "EmployeeLeftEvent": { "allOf": [ { "$ref": "#/components/schemas/WebhookEvent" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "employee.left" ], "description": "Event type for employee terminated or on Garden leave" }, "data": { "$ref": "#/components/schemas/EmployeeLifecycleEventData" } } } ] }, "EmployeeActivatedEvent": { "allOf": [ { "$ref": "#/components/schemas/WebhookEvent" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "employee.activated" ], "description": "Event type for employee access enabled" }, "data": { "$ref": "#/components/schemas/EmployeeLifecycleEventData" } } } ] }, "EmployeeInactivatedEvent": { "allOf": [ { "$ref": "#/components/schemas/WebhookEvent" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "employee.inactivated" ], "description": "Event type for employee inactivated (on leave or terminated)" }, "data": { "$ref": "#/components/schemas/EmployeeLifecycleEventData" } } } ] }, "EmployeeTemporaryLeaveEvent": { "allOf": [ { "$ref": "#/components/schemas/WebhookEvent" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "employee.temporaryLeave" ], "description": "Event type for employee on temporary leave" }, "data": { "$ref": "#/components/schemas/EmployeeLifecycleEventData" } } } ] }, "TableEntryCreatedEvent": { "allOf": [ { "$ref": "#/components/schemas/WebhookEvent" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "table.entry.created" ], "description": "Event type for table entry created" }, "data": { "$ref": "#/components/schemas/TableEntryEventData" } } } ] }, "TableEntryUpdatedEvent": { "allOf": [ { "$ref": "#/components/schemas/WebhookEvent" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "table.entry.updated" ], "description": "Event type for table entry updated" }, "data": { "$ref": "#/components/schemas/TableEntryEventData" } } } ] }, "ReadEmployeesRequestReference": { "type": "object", "properties": { "fields": { "type": "array", "description": "Optional field IDs to return (max 400). Dot notation from Fields metadata (e.g. root.id). Omit for the default field set. See Critical behaviors below on this page.", "items": { "type": "string" }, "example": [ "root.id", "root.firstName" ] }, "filters": { "type": "array", "description": "Optional. One filter on root.id or root.email with operator equals. Omit when not filtering. See Critical behaviors below on this page.", "items": { "$ref": "#/components/schemas/EmployeeFilter" } }, "showInactive": { "type": "boolean", "default": false, "description": "Include inactive (typically terminated/former) employees. Default false (active only). See Critical behaviors below on this page.", "example": false }, "humanReadable": { "type": "string", "default": "", "description": "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.
" } }, "default": { "fields": [ "root.id", "root.firstName" ], "showInactive": false, "humanReadable": "", "filters": [ { "fieldPath": "root.id", "operator": "equals", "values": [ "3332883884017713938", "3332883909410030364" ] } ] } }, "EmployeeFilter": { "type": "object", "properties": { "fieldPath": { "type": "string", "enum": [ "root.id", "root.email" ], "example": "root.id", "description": "The field ID to filter by (dot notation, as returned by Fields metadata). Supported values: root.id, root.email. Any other field ID returns 400 HTTP error." }, "operator": { "type": "string", "example": "equals", "description": "Supported operators: “equals”
Any other operator will get a response of 400 HTTP error." }, "values": { "type": "array", "description": "The list of values to compare with the operator. An Empty list will result in 400 HTTP error.", "items": { "type": "string" }, "example": [ "", "" ] } } }, "WorkPartReadable": { "type": "object", "properties": { "shortStartDate": { "type": "string", "description": "The employee's employment start date without the year", "format": "date" }, "startDate": { "type": "string", "description": "The employee's employment start date without the year", "format": "date" }, "manager": { "type": "string", "description": "The full name of the employee's manager." }, "tenureDuration": { "type": "string", "description": "The tenure duration of the employee." }, "durationOfEmployment": { "type": "string", "description": "The tenure duration of the employee." }, "reportsToIdInCompany": { "type": "string", "description": "The ID in company of the manager." }, "employeeIdInCompany": { "type": "string", "description": "The ID of the manager." }, "reportsTo": { "type": "string", "description": "The full name of the person the employee reports to." }, "tenureDurationYears": { "type": "string", "description": "The tenture duration in years." }, "department": { "type": "string", "description": "The department this employee belong to." }, "siteID": { "type": "string", "description": "The ID of the site the employee belongs to." }, "tenureYears": { "type": "string", "description": "The tenture in years." }, "isManager": { "type": "string", "description": "Is the employee a manager (Yes/No)." }, "title": { "type": "string", "description": "The employee's title." }, "site": { "type": "string", "description": "The employee's site." }, "originalStartDate": { "type": "string", "description": "The original date the employee started to work" }, "activeEffectiveDate": { "type": "string", "description": "The active effective date the employee started to work" }, "secondLevelManager": { "type": "string", "description": "The full name of the manager in the second level" }, "daysOfPreviousService": { "type": "string", "description": "The number of days in previous service" }, "yearsOfService": { "type": "string", "description": "The number of years in service" } } }, "AboutPartReadable": { "type": "object", "properties": { "foodPreferences": { "type": "string", "description": "Employee's food preferences." }, "superpowers": { "type": "string", "description": "Employee's super powers." }, "hobbies": { "type": "string", "description": "A list of the employee's hobbies." }, "about": { "type": "string", "description": "Employee's about sentence." }, "avatar": { "type": "string", "description": "Image URL of the employee's avatar." } } }, "WorkPartMachineFormat": { "type": "object", "properties": { "shortStartDate": { "type": "string", "description": "The employee's employment start date without the year", "format": "date" }, "startDate": { "type": "string", "description": "The employee's employment start date without the year", "format": "date" }, "manager": { "type": "string", "description": "The full name of the employee's manager." }, "tenureDuration": { "type": "object", "description": "The tenure duration of the employee.", "properties": { "periodISO": { "type": "string" }, "sortFactor": { "type": "number" }, "humanize": { "type": "string" } } }, "custom": { "description": "The custom fields of the employee.", "type": "array", "items": { "type": "string" } }, "durationOfEmployment": { "type": "object", "description": "The tenure duration of employment of the employee.", "properties": { "periodISO": { "type": "string" }, "sortFactor": { "type": "number" }, "humanize": { "type": "string" } } }, "reportsToIdInCompany": { "type": "number", "description": "The ID in company of the manager." }, "employeeIdInCompany": { "type": "number", "description": "The ID of the manager." }, "reportsTo": { "type": "object", "description": "The full name of the person the employee reports to.", "properties": { "displayName": { "type": "string" }, "email": { "type": "string" }, "surname": { "type": "string" }, "firstName": { "type": "string" }, "id": { "type": "string" } } }, "workMobile": { "type": "string", "description": "The work mobile number." }, "workPhone": { "type": "string", "description": "The work phone number." }, "indirectReports": { "type": "number", "description": "The person this employee reports to indirectly." }, "siteID": { "type": "number", "description": "The ID of the site the employee belongs to." }, "tenureDurationYears": { "type": "number", "description": "The tenture duration in years." }, "department": { "type": "string", "description": "The department this employee belong to." }, "tenureYears": { "type": "number", "description": "The tenture in years." }, "isManager": { "type": "string", "description": "Is the employee a manager (Yes/No)." }, "title": { "type": "string", "description": "The employee's title." }, "site": { "type": "string", "description": "The employee's site." }, "originalStartDate": { "type": "string", "description": "The original date the employee started to work" }, "activeEffectiveDate": { "type": "string", "description": "The active effective date the employee started to work" }, "directReports": { "type": "number", "description": "The internal ID of the person this employee reports to directly" }, "secondLevelManager": { "type": "string", "description": "The ID of the manager in the second level" }, "daysOfPreviousService": { "type": "number", "description": "The number of days in previous service" }, "yearsOfService": { "type": "number", "description": "The number of years in service" } } }, "AboutPartMachineFormat": { "type": "object", "properties": { "foodPreferences": { "type": "array", "description": "Employee's food preferences.", "items": { "type": "string" } }, "socialData": { "type": "object", "description": "Employee's social data.", "properties": { "linkedin": { "type": "string" }, "twitter": { "type": "string" }, "facebook": { "type": "string" } } }, "superpowers": { "type": "array", "description": "Employee's super powers.", "items": { "type": "string" } }, "hobbies": { "type": "array", "description": "A list of the employee's hobbies.", "items": { "type": "string" } }, "about": { "type": "string", "description": "Employee's about sentence." }, "avatar": { "type": "string", "description": "Image URL of the employee's avatar." } } }, "EmployeeResponseReadable": { "title": "Human readable only (humanReadable=\"REPLACE\")", "type": "object", "properties": { "fullName": { "type": "string", "description": "The full name of the Employee (first name + surname)." }, "displayName": { "type": "string", "description": "Employee's display name. This defaults to first name & last name but can be customized." }, "creationDateTime": { "type": "string", "description": "The full timestamp of creation of the Employee." }, "work": { "anyOf": [ { "$ref": "#/components/schemas/WorkPartReadable" } ] }, "avatarUrl": { "type": "string", "description": "The URL of the source of the avatar image." }, "secondName": { "type": "string", "description": "Employee's surname." }, "about": { "anyOf": [ { "$ref": "#/components/schemas/AboutPartReadable" } ] }, "companyId": { "type": "string", "description": "The ID of the employee's company." }, "email": { "type": "string", "description": "Employee's email address.", "format": "email" }, "surname": { "type": "string", "description": "Employee's surname." }, "coverImageUrl": { "type": "string", "description": "The URL of the cover image." }, "id": { "type": "string", "description": "A unique identifier representing a specific employee." }, "firstName": { "type": "string", "description": "Employee's first name." } } }, "EmployeeResponseMachineFormat": { "title": "Machine format only (humanReadable=\"\")", "type": "object", "properties": { "fullName": { "type": "string", "description": "The full name of the Employee (first name + surname)." }, "/work/indirectReports": { "type": "array", "description": "The internal IDs of the people the Employee reports to indirectly.", "items": { "type": "string" } }, "/about/avatar": { "type": "object", "description": "The avatar URL of the employee.", "properties": { "value": { "type": "string" } } }, "/work/reportsTo/email": { "type": "object", "description": "The email of the person the employee reports to.", "properties": { "value": { "type": "string" } } }, "displayName": { "type": "string", "description": "Employee's display name. This defaults to first name & last name but can be customized." }, "/root/firstName": { "type": "object", "description": "The first name of the employee.", "properties": { "value": { "type": "string" } } }, "/work/employeeIdInCompany": { "type": "object", "description": "The internal ID of the employee.", "properties": { "value": { "type": "number" } } }, "/work/tenureDurationYears": { "type": "object", "description": "The tenure duration in exact years of the employee.", "properties": { "value": { "type": "number" } } }, "/about/foodPreferences": { "type": "object", "description": "The food preferences of the employee.", "properties": { "value": { "type": "string" } } }, "/work/site": { "type": "object", "description": "The site name of the employee.", "properties": { "value": { "type": "string" } } }, "/work/tenureYears": { "type": "object", "description": "The tenure duration in years of the employee (rounded value).", "properties": { "value": { "type": "string" } } }, "creationDateTime": { "type": "string", "description": "The full timestamp of creation of the Employee." }, "hobbies": { "type": "object", "properties": { "value": { "type": "array", "description": "An array of the employee's hobbies.", "items": { "type": "string" } } } }, "/root/email": { "type": "object", "description": "The employee's email.", "properties": { "value": { "type": "string" } } }, "/work/title": { "type": "object", "description": "The employee's title.", "properties": { "value": { "type": "string" } } }, "employee": { "type": "object", "properties": { "payrollManager": { "type": "string" }, "hrbp": { "type": "string" }, "itAdmin": { "type": "string" }, "buddy": { "type": "string" } } }, "work": { "type": "object", "anyOf": [ { "$ref": "#/components/schemas/WorkPartMachineFormat" } ] }, "avatarUrl": { "type": "string", "description": "The URL of the source of the avatar image." }, "secondName": { "type": "string", "description": "Employee's surname." }, "about": { "type": "object", "anyOf": [ { "$ref": "#/components/schemas/AboutPartMachineFormat" } ] }, "/root/fullName": { "type": "object", "description": "The employee's full name.", "properties": { "value": { "type": "string" } } }, "companyId": { "type": "number", "description": "The ID of the employee's company." }, "/root/coverImageUrl": { "type": "object", "description": "The employee's cover image.", "properties": { "value": { "type": "string" } } }, "/work/secondLevelManager": { "type": "object", "description": "The ID of the second level manager of the employee.", "properties": { "value": { "type": "string" } } }, "/work/directReports": { "type": "object", "description": "The number of people the employee reports to directly.", "properties": { "value": { "type": "number" } } }, "/work/yearsOfService": { "type": "object", "description": "The number of years the employee has been in service.", "properties": { "value": { "type": "number" } } }, "/work/daysOfPreviousService": { "type": "object", "description": "The number of years the employee has been in service previously.", "properties": { "value": { "type": "number" } } }, "/about/about": { "type": "object", "description": "Employee's about sentence.", "properties": { "value": { "type": "string" } } }, "/root/avatarUrl": { "type": "object", "description": "The url for the avatar file of the employee.", "properties": { "value": { "type": "string" } } }, "/work/shortStartDate": { "type": "object", "description": "The start date of the employee in a short format (without the year).", "properties": { "value": { "type": "string" } } }, "/work/activeEffectiveDate": { "type": "object", "description": "The date the employee bacame active.", "properties": { "value": { "type": "string" } } }, "/root/id": { "type": "object", "description": "The ID of the employee.", "properties": { "value": { "type": "string" } } }, "email": { "type": "string", "description": "Employee's email address.", "format": "email" }, "/work/manager": { "type": "object", "description": "The ID of the employee's manager.", "properties": { "value": { "type": "string" } } }, "surname": { "type": "string", "description": "Employee's surname." }, "/work/reportsTo": { "type": "object", "description": "The details of the person the employee reports to.", "properties": { "value": { "type": "object", "properties": { "displayName": { "type": "string" }, "email": { "type": "string" }, "surname": { "type": "string" }, "firstName": { "type": "string" }, "id": { "type": "string" } } } } }, "/root/companyId": { "type": "object", "description": "The ID of the employee's company.", "properties": { "value": { "type": "number" } } }, "/root/displayName": { "type": "object", "description": "The display name of the employee.", "properties": { "value": { "type": "string" } } }, "/work/department": { "type": "object", "description": "The department of the employee.", "properties": { "value": { "type": "string" } } }, "/work/isManager": { "type": "object", "description": "The department of the employee.", "properties": { "value": { "type": "boolean" } } }, "/work/originalStartDate": { "type": "object", "description": "The original date the employee started work.", "properties": { "value": { "type": "string" } } }, "coverImageUrl": { "type": "string", "description": "The URL of the cover image." }, "/work/reportsToIdInCompany": { "type": "object", "description": "The ID of the person this employee reports to.", "properties": { "value": { "type": "number" } } }, "/work/tenureDuration": { "type": "object", "description": "The tenture duration of the employee.", "properties": { "value": { "type": "object", "properties": { "periodISO": { "type": "string" }, "sortFactor": { "type": "number" }, "humanize": { "type": "string" } } } } }, "/about/superpowers": { "type": "object", "description": "The super powers of the employee.", "properties": { "value": { "type": "array", "items": { "type": "string" } } } }, "id": { "type": "string", "description": "A unique identifier representing a specific employee." }, "firstName": { "type": "string", "description": "Employee's first name." }, "/work/siteId": { "type": "object", "description": "The site ID of the employee's site.", "properties": { "value": { "type": "number" } } }, "/work/durationOfEmployment": { "type": "object", "description": "The duration of the employee's employment.", "properties": { "value": { "type": "object", "properties": { "periodISO": { "type": "string" }, "sortFactor": { "type": "number" }, "humanize": { "type": "string" } } } } } } }, "Employees": { "type": "object", "description": "Employee read response for Search for employees. Contains all matching employees for the request in one employees array (not split across pages). Machine-format field values use slash-notation keys (e.g. /root/id) with a value property. The same employee object may also include nested category objects (e.g. work.siteId). Request field IDs use dot notation from metadata (e.g. root.id). See People read API contract.", "properties": { "employees": { "type": "array", "description": "All employees matching the search request and service user scope for this call.", "items": { "oneOf": [ { "$ref": "#/components/schemas/EmployeeResponseReadable" }, { "$ref": "#/components/schemas/EmployeeResponseMachineFormat" } ] } } } }, "Error": { "type": "object", "properties": { "key": { "type": "string", "description": "The unique identifier of the error." }, "error": { "type": "string", "description": "A human readable error message." } } } }, "securitySchemes": { "Basic": { "type": "http", "scheme": "basic", "description": "Basic HTTP authentication using service user credentials" }, "Bearer": { "type": "http", "scheme": "bearer", "bearerFormat": "OAuth 2.0", "description": "OAuth 2.0 authentication using an Access Token is available for registered partners only. Try It! does not support the full HiBob OAuth flow. You can follow these steps to complete the OAuth 2.0 flow in Postman and then paste the token here." } } } } ```