--- updatedAt: 2026-08-13T06:27:21.000Z --- Fetch the complete documentation index at: https://apidocs.hibob.com/llms.txt. Use this file to discover all available pages before exploring further. # Explore Employee data API Understand the basic concepts of employee data API in Bob # Overview Bob's Public APIs and Webhooks offer developers a programmatic way to access employee data efficiently. Using the REST API and Webhooks, you can communicate with Bob and leverage employee data for various business needs. ### Prefer to listen? Scroll down for an [audio summary](#-audio-recap-ai-generated). ## People's data fields Bob comes with a predefined set of Employee Fields, Employee Tables, and categories that cover Bob's functionality, which is referred to as out-of-the-box (OOTB). Any new Fields, Tables, or Categories added by users are called "custom fields," "custom tables," and "custom categories," allowing for further customization based on specific requirements. Both OOTB and Customized data fields can be accessed via the Public API. To learn more about customizing the employee data, see Set up People's data fields ↗. # Employee data modeling The **Employee Data API** organizes data into **Categories**, which group related fields and tables. **Employee Fields can be either:** * **Non-historical** : These are the standard data fields that hold a single value. * Fields can be of any of the supported [data types](/docs/fields-metadata#field-types). * Existing fields can be customized. * Users can create new custom fields. * **Historical** : Fields that have an 'effective date'. * Historical fields can store several values, each with an effective date. * Based on the current date, the values with a current effective date are considered the 'current value' for this field. * Existing historical fields can be customized. * Users can create new custom fields. * **Calculated** (read-only): Dynamically generated values based on other fields. * For example, Full Name is actually calculated based on First name + Middle name + Last name. * When editing the employee data from the UI, calculated fields are grayed out and cannot be updated. * Calculated fields can not be customized or created by users. * Cannot be mapped to third-party fields when setting up integrations. **Columns are fields within tables that store more multi-record data and can be either:** * **Historical tables**: These are out-of-the-box tables that track changes over time. Each row has an 'effective date'. Based on the current date, rows with the current effective date are considered the **current data** of the employee (green dot in UI) and can be retrieved when using the Employee Search API. Historical tables can be: * **Single current**: The 'Effective Date' is the only key. For example, the **Work** table. * **Multi current**: Tables with a secondary key (in addition to the 'effective date') can have a few' current' rows. For example, **Variable Pay** table with the key:**Effective date + Variable type**. * **Non-historical Tables**: Do not have an 'effective date'. ### Note: Calculated fields, and historical tables cannot be created by the user or via the Public API. # Data access via the Public API The following tables will help you determine which fields and tables can be accessed via the Public API and which endpoints you need to use for each.
Data type Description Relevant to Relevant endpoints Included in fields metadata Can be customized by the user
Fields Employee fields can be of any supported [data types](/docs/fields-metadata#field-types) . All OOTB fields. Historical tables' 'current' values. People data + Fields Metadata Yes Yes
Historical fields Fields with an 'effective date'. **'Disability Status'** People data Yes (current value only) Yes
Calculated Fields Fields calculated based on existing fields For example: **Full Name** People data + Fields Metadata Yes No
Lists List items can be a value of a field. The list item can be a backend-id or the display value. **All fields** People data + Fields Metadata No Yes
Historical Tables: Single current Single row with the 'current effective date' **Work Employment Payroll/Salary Lifecycle** + Address (no table endpoint) People data + Employee Tables (besides Address) Yes No
Historical Tables: Multi current Multiple rows can be active based on the 'effective date' and additional keys. **Variable Pay,**
**Deduction, Entitlement** 		People data Yes No
Non-historical tables Tables that can have duplicate rows **Custom Tables**,
**Actual Payments, Bank Accounts, Training, Equity** 		Employee Tables No
(see note 2) 		Yes
### **Notes**: 1. **Out-of-the-box tables**: - Not all historical tables have an endpoint which allows to read all records. For these tables you can use the People Search endpoint in order to fetch the 'current' row's data: **Entitlement**, **Deduction**, and **Address**. - The following tables cannot be accessed via the public API: **Entitlement**, **Deduction**, and **Address** (for full history). Dependents (internal kids table) are available via `/v1/people/{id}/dependents` and `/v1/bulk/people/dependents`. Right to Work is available via `/v1/people/{id}/right-to-work` and `/v1/bulk/people/right-to-work`. 2. **Actual Payments**: The Actual Payments table's fields **cannot be retrieved using the People Search endpoint** even though the columns are returned from the fields metadata (legacy). You should use the dedicated **Search Actual Payments** endpoint for this table. 3. **Positions**: The **Positions** table is part of the Workforce Planning module. To access positions, use [Workforce Planning endpoints](/reference/workforce-planning) rather than the People's data API. 4. **Jobs**: The **Jobs** table is basically a reference to Job catalog. To get the employee's assigned job: - For the **new Job Catalog 2.0,** use `employee.jobProfileId` and fetch job details from the [Job catalog endpoints](https://apidocs.hibob.com/reference/job-catalog) . **Migration note**: If you migrated from the old catalog,you can still use `employee.jobLevelId`, however, it will return the same value as `jobProfileId` for backward compatibility. - When using the **old job catalog**, fetch the `employee.jobLevelId` to view the current job assigned to the employee. # Public API ## Metadata endpoints The metadata endpoints provide access to fields and list properties.
Type Descriptions API Endpoints
Fields metadata Use this endpoint to obtain the properties of fields and historical-tables. The metadata returns all the fields that are considered the 'current' data of the employee [Get all employee fields](/reference/get_company-people-fields) [Create a new field](/reference/post_company-people-fields) [Update an existing field ](/reference/put_company-people-fields-fieldid) [Delete an existing field.](/reference/delete_company-people-fields-fieldid)
Lists metadata Use these endpoints to obtain and manage the properties of lists [Get all company lists](/reference/get_company-named-lists) [Get a specific company list by name](/reference/get_company-named-lists-listname) [Add a new item to an existing list](/reference/post_company-named-lists-listname) [Add a new item to an existing list](/reference/put_company-named-lists-listname-itemid)
To learn more, see [Metadata endpoints](/reference/metadata). ## Employee data endpoints The endpoints that provide access to the employee data include:
Type Description API Endpoints
Get people data Provide access to out-of-the-box fields, custom fields and current values of historical tables [Search for employees](/reference/post_people-search) [Read company employee fields by employee](/reference/post_people-identifier) [Read the public profile of active employees](/reference/get_profiles)
Create Use this endpoint to create an employee and get it's details back [Create company employee](/reference/post_people)
Update Update specific fields in an employee's record and change the employee's status [Create company employee](/reference/post_people) [Terminate](/reference/post_employees-identifier-terminate) [Revoke access](/reference/post_employees-identifier-uninvite) [Invite](/reference/post_employees-employeeid-invitations) [set start date](/reference/post_employees-employeeid-start-date)
Avatar Manage avatar image files [Upload avatar](/reference/put_avatars-employeeid) [Read avatar by email](/reference/get_avatars) [Read avatar by ID](/reference/get_avatars-employeeid)
Email Update the employee's work email address [Update the employee's email](/reference/put_people-id-email)
## OOTB tables endpoints The out-of-the-box tables in Bob are designed to support employee employment and lifecycle flows. The table below outlines which tables are accessible and highlights any limitations for specific tables. | Categoryin Employee Data | Description | Actions & Limitations | API Endpoints | | :----------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Lifecycle | Automatically reflects the employee’s lifecycle based on user actions in Bob, such as rehiring, placing or returning from leave, and employee termination. To learn more, check out the [lifecycle status in Bob](https://help.hibob.com/hc/en-us/articles/4409776355857-Employee-lifecycle-status#h_01H95TQ2DCZ25SPT6R7CYCC0ZW). | The changes are logged as Lifecycle entries and impact employee status. Entries cannot be added/removed by users. | [Get](/reference/get_people-id-lifecycle) [bulk get](/reference/get_bulk-people-lifecycle) | | Work | Reflects the employee’s work history. | Changes in the Lifecycle influence the Work status. | [Get](/reference/get_people-id-work) [bulk get](/reference/get_bulk-people-work) [create](/reference/post_people-id-work) [update](/reference/put_people-id-work-entry-id) [delete](/reference/delete_people-id-work-entry-id) | | Employment | Captures the employee’s employment history, including job terms and working patterns. | | [Get](eference/get_people-id-employment/reference/get_people-id-employment) [bulk get](/reference/get_bulk-people-employment) [create](/reference/post_people-id-employment) [update](/reference/put_people-id-employment-entry-id) [delete](/reference/delete_people-id-employment-entry-id) | | Salary
(Payroll) | Captures the employee’s salary terms and history. | | [Get](/reference/get_people-id-salaries) [bulk get](/reference/get_bulk-people-salaries) [create](/reference/post_people-id-salaries) [delete](/reference/delete_people-id-salaries-entry-id) | | Variable Pay
(Payroll) | Part of Payroll category; includes variable payments information. | | [Get](/reference/get_people-id-variable) [create](/reference/post_people-id-variable) [delete](/reference/delete_people-id-variable-entry-id) | | Actual Payments
(Payroll) | Part of Payroll category; stores actual payments made. | Non-historical table. | [Search](/reference/post_people-actual-payments-search) functionality only | | Bank Accounts
(Payroll) | Part of Payroll category; stores bank account details. | Non-historical table. | [Get](/reference/get_people-id-bank-accounts) [create](/reference/post_people-id-bank-accounts) [update](/reference/put_people-id-bank-accounts-entry-id) [delete](eference/delete_people-id-bank-accounts-entry-id/reference/delete_people-id-bank-accounts-entry-id) | | Equity
(Payroll) | Part of Payroll category; Lists equity grants. | Non-historical table. | [Get](/reference/get_people-id-equities) [Create](/reference/post_people-id-equities)[update](/reference/put_people-id-equities-entry-id) [delete](/reference/delete_people-id-equities-entry-id) | | Training | Part of the Training category. | Non-historical table. | [Get](/reference/get_people-id-training) [create](/reference/post_people-id-training) [delete](/reference/delete_people-id-training-entry-id) | The [Employee Tables API](/reference/employee-tables) reference lists the Public API endpoints. ## Custom tables endpoints The table below outlines how to access custom in Bob:
Type Description API Endpoints
Custom tables metadata Use these endpoints to obtain the properties of custom tables [Read metadata of custom tables defined](/reference/get_people-custom-tables-metadata) [Read metadata for specific custom table](/reference/get_people-custom-tables-metadata-custom-table-id)
Get entries Read all the entries of a custom table [Read entries](/reference/get_people-custom-tables-employee-id-custom-table-id)
Create, Update, and Delete entries [Create new custom table entry](/reference/post_people-custom-tables-employee-id-custom-table-id) [Update custom table entry](/reference/put_people-custom-tables-employee-id-custom-table-id-entry-id) [Delete custom table entry](/reference/delete_people-custom-tables-employee-id-custom-table-id-entry-id)
For the complete reference guide, see [Custom Tables](/reference/custom-tables) ## Employee webhook events Bob allows you to subscribe to system events by providing a webhook URL as a listener. When an event occurs, Bob will call this listener and send details in the event's payload. Each webhook event sends information specific to the event, and the listener can then make an API call to retrieve additional data as needed for further context. Employee webhook events include: * Creating and updating the employee profile. * Changes to the employee's lifecycle. * Updating employee tables. A common use case for subscribing to Bob's webhook events is to keep external systems, like payroll or identity management tools, in sync with Bob. When an employee profile is updated, the Webhook event serves as a notification to the connected system, prompting it to call Bob's API to retrieve all relevant details. This ensures data consistency across platforms without manual input, automating updates efficiently. To learn more, see [Getting started with Webhooks](/reference/getting-started-webhooks). For the reference guide, see [Employee data webhook events](https://apidocs.hibob.com/reference/employee-data-webhooks). # Permissions Categories are the primary unit for assigning permissions to access fields and tables. Each category is identified by a unique category ID, which varies between out-of-the-box categories and user-defined categories. To learn more about each category, see [People's data fields glossary](https://help.hibob.com/hc/en-us/articles/16157839007121-People-s-data-fields-glossary#h_01HA252C5NBBNK3D18WW1PW7CS). When using the Bob API, you need to authenticate with a Service User and assign the relevant permissions: * **[Service Users](/docs/api-service-users):** API service users in Bob allow you to access APIs in Bob. Multiple service users can be created, each with unique permissions, depending on the API you want to access. * **Permissions**: are always assigned to categories rather than individual fields. * **Permission groups**: Give you control over what information and functionalities each service user can access. To learn more, see [Categories and permissions](/docs/categories-and-permissions). # Lists Fields can be linked to a list, which holds string item values. Lists can be out-of-the-box or custom (defined by the user). All lists and their values can be retrieved using the lists metadata API. **List items backend-IDs** Each list item has a backend ID, which represents the id of the item in the list as stored in the database. The id can be a text (for out-of-the-box lists) or a number (for custom lists). In order to view the string value of the list item, you should [convert it to human-readable format](#converting-list-items-to-human-readable-format). To learn more, see [Fields and lists metadata](/docs/fields-metadata). # 🎧 Audio Recap (AI-generated) > **Note:** This audio was generated by artificial intelligence and may contain inaccuracies or outdated information. It is provided for informational purposes only, and any use is at the listener's discretion. The content is based on material found in the Bob Help Center and Bob Developer Hub. ### Read employee data summary (12 min.)

# Related resources * [How to read employee data](/docs/how-to-read-employee-data). * [Working with employee search endpoint](/docs/how-to-read-employee-data-tutorial). * [People API reference](/reference/people). * [People Tables reference](/reference/employee-tables). * [Categories and permissions](/docs/categories-and-permissions). * [Set up People's data fields](https://help.hibob.com/hc/en-us/articles/4409776099473-Set-up-people-s-data-fields#01H8E2C7A1AW519V81ZSSDVHCN). * [Rate limiting](/docs/rate-limit). * [Getting started with Bob API](/reference/getting-started-with-bob-api).