Employee data can be represented in fields or in tables. Tables group a few fields (aka columns) and allow storing the data as rows, each row representing an entry. Bob comes with out-of-the-box (OOO) fields and tables, and users can add custom fields, custom columns to existing tables, and custom tables.

Additional employee data types:

• Out-of-the-box tables: See Employee Tables endpoints.
• Custom tables: See Custom tables endpoints.

Out-of-the-box tables

Bob comes with out-of-the-box tables that hold employee data.

There are two types of tables:

• Simple tables: hold multiple entries of data, such as Variable payments.
• Historical tables: include historical data about the employee, and an effective date, allowing for tracking of information over time. Historical tables include: Work, Employment, Payroll, and Lifecycle.

Historical tables (have 'effective date')

Each row in the historical tables includes an effective date, which indicates when the information in that row takes effect and impacts the employee's status. Only a single row can be effective at any given time.

For example, if an employee is terminated and a row is added to the Lifecycle table with an effective date of April 17, the termination will take effect at midnight on April 18 (according to the site’s timezone).

📘

Reading historical entries

When reading basic employee data, you will see only entries with the current effective date. If you want to read all the entries, you should use Employee Tables endpoints and ensure the service user has permissions to access history:

People’s data permissions > People > Category-name > View selected employees' Category-name > section histories.

Read table data for several employees (bulk)

You can read out-of-the-box tables entries for several employees in a single call, using pagination for better performance.

To do this, use the bulk endpoints that are listed in the Employee Tables endpoints.

Custom columns in out-of-the-box tables

Out-of-the-box employee tables can have out-of-the-box columns and custom columns which are defined by the user. When reading the table data via the public API, the custom columns will be returned in the customColumns field.

Example:

 "customColumns": {
        "column_1720616785883": 3
 }

Make sure to check the custom column's data type using the custom table's fields metadata endpoints so you process the data correctly.

Custom tables

Custom tables are tables defined by the user.

When reading the employee data using the employees search endpoint you will not receive the data for the custom tables. To read custom tables data you first need to discover which custom tables are defined and then read the custom table data for the employee.

Custom tables metadata endpoints

To access custom tables metadata you can use these endpoints:

• Read metadata of custom tables defined: read metadata for all tables
• Read metadata for specific custom table: read metadata for a specific table.
• Other endpoints in Custom Tables: read and update custom table entries.

Example

1. Discover custom tables:

GET https://api.hibob.com/v1/people/custom-tables/metadata

2. Extract the custom table you want to read and fetch the category from the metadata to ensure the service user has permission to access this category.

{
            "id": "about__table_1720510199232",
            "name": "custom table in about",
            "category": "about",
            "description": null,
            "columns": [
                {
                    "id": "column_1720510217232",
                    "name": "custom column in about - date",
                    "description": null,
                    "mandatory": false,
                    "type": "date",
                    "typeData": {}
                },
                {
                    "id": "column_1720510229276",
                    "name": "custom column in about - data",
                    "description": null,
                    "mandatory": false,
                    "type": "text",
                    "typeData": {}
                }
            ]
        

2. Extract the custom table ID and read the custom table’s data for a specific employee:

GET https://api.hibob.com/v1/people/custom-tables/3332883884017713938/about__table_1720510199232

{
  "values": [
    {
      "column_1720510217232": "2024-07-15",
      "changedBy": "3332883804594373380",
      "id": 4617235,
      "column_1720510229176": "test custom data"
    },
  ]
}