In Bob, a field stores employee data, either as an individual field or a column in a table. The field's metadata defines its properties—such as ID, category, and type—helping you understand and process the data effectively

This article explains field types, custom fields, human-readable values, and how to manage lists using the Public API.

Field Types

The field type determines how you should approach the data. For example, a "short date" will not contain the year (e.g., "08-10") as opposed to a "date" (e.g., "1986-08-10"). Another example is a "list," which will contain the list item's string ID rather than its value, and you will need to extract the values using the list's metadata.

Some fields have a 'backend value,' which is the internal representation of fields stored in the database. This is often used for fields that hold system values (like ISO dates) or IDs of items in a list. The human-readable value column in the table below shows the actual values returned for these fields. These values are displayed when the "humanReadable" flag is used to retrieve them. Note that human-readable values will be returned only for fields with an actual value (not "null" ). To learn more, see Human-readable values.

Field types can be any of the data types supported by Bob:

To learn more about field types in Bob, see Set up people's data fields ↗.

Custom data in the Public API

Bob lets admins add custom configuration in several places. Each type uses different metadata, response shapes, and update endpoints. Use the table below as a map, then follow the sections that match your integration.

Custom data types at a glance

Custom employee fields (category fields)

Employee categories may include custom fields. They are not returned in default profile/search responses; request them by metadata id in the fields parameter (Search) or read them via Profiles when included in the schema.

Metadata example:

{
        "id": "work.custom.field_1711886937296", // the custom field ID
        "category": "work",
        "name": "Has Dog",
        "description": null,
        "jsonPath": "work.custom.field_1711886937296",
        "type": "number",
        "typeData": {},
        "historical": false
    }

Custom categories: Fields can sit in out-of-the-box categories (work, about, …) or in admin-defined categories. Custom categories use IDs like category_1720508362305 in metadata (see the category note under Get all employee fields). Permissions follow that category.

Custom fields and custom columns in API responses

Bob distinguishes two kinds of user-defined data:

• Custom field: Field on a category (Work, About, etc.)
  • Metadata field ID pattern: {category}.custom.field_{id}
  • Example: work.custom.field_1711886937296
• Custom column: Column on a table (OOTB or custom
  • Metadata field ID pattern: {table}.customColumns.column_{id} or column metadata on custom tables
  • Example: work.customColumns.column_1732443454173

Always use the Fields metadata endpoint to resolve the exact id and jsonPath for the field or column you need.

Where custom field values appear in responses

The same logical column can appear in different JSON shapes depending on which endpoint you call:

Profiles and People Search (category fields)

Read profiles and Search employees return custom fields nested under the category’s custom object. Keys use the field_ prefix only (without the category prefix):

"work": {
  "department": "Product",
  "custom": {
    "field_1711886937296": "value or null"
  }
}

Request these fields explicitly in Search by listing their metadata id (for example work.custom.field_1711886937296). Empty custom fields are often omitted or returned as null.

Out-of-the-box table endpoints (custom columns)

When you read rows from an Employee table endpoint (for example Work, Training, Salary), user-defined columns are grouped under customColumns. Keys use the column_ prefix:

{
  "id": 12345,
  "title": "Engineer",
  "customColumns": {
    "column_1732443454173": "123123",
    "column_1720966485336": "261352785"
  }
}

This applies to non-historical tables (for example Training) and to each row in historical tables (for example Work).

Custom table endpoints (custom columns as top-level keys)

Custom table rows use the same column_{id} keys, but not inside a customColumns object—they are top-level properties on each entry:

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

Discover column IDs from custom table metadata.

Metadata endpoints

The metadata endpoints provide access to fields, list properties, and settings.

Dynamic entities provide metadata endpoints so you can find the dynamic (customer-defined) fields and values.

Note: only dynamic entities require metadata endpoints. Entities that are not dynamic (like time-off requests or tasks) provide a static set of available fields in the endpoint's definition.

Fields metadata

The metadata is accessed via dedicated metadata endpoints, which don't require special permissions.

The field metadata includes the ID, the category, and the type.

• Field ID: The field ID is the string you must specify in the query you send to the search API. Fetching field metadata will return all the fields, including custom fields defined by the user. This will allow you to specify any field you need in the query.
• Field Category: The field category is available only for employee-data fields. This helps you to determine how to grant access to the service user. The employee-data search API will not return this field in the response without granting permissions to the field's category.
• Field Data Type: You need to know the data type to process the field values correctly in the response payload. To learn more, see Field Types.

Field ID notation

Field IDs come from Fields metadata. The metadata id property uses dot notation — this is the canonical field ID (e.g. "id": "work.department").

Requests — use dot notation

Use the metadata id value directly in fields[] and filter fieldPath:

"fields": [
  "root.id",
  "root.firstName",
  "work.department"
]

For the full request/response contract (permissions, silent omission, filters), see People read API contract.

Note: Slash notation (e.g. /root/id) may be accepted in some requests, but dot notation is canonical. Always copy field IDs from metadata.

Responses — slash notation

Response payloads always use slash notation for machine-format field keys:

"/root/id": { "value": "3332883884017713938" },
"/work/department": { "value": "209192163" }

The same employee object may also include nested category objects (e.g. "work": { "siteId": 2510068 } alongside "/work/siteId"). See People read API contract — Dual shapes.

Human-readable values

When fetching data from the database, some fields may contain a value that is not the same value you would see in the UI, referred to as the machine-format.

For example:

• ISO time - holds an ISO representation of time.
• Boolean - hold boolan true/false values.
• List items - store the backend ID. To learn more, see Lists.
• Employee reference - store the backend ID of a related employee.

In order to view the string value of the fields, you should convert it to human-readable format.

Some endpoints, like the People Search, support the humanReadable flag. Using this flag, you can retrieve the human-readable values of the list while querying the data, either in addition to the machine-format values or instead of the machine-format values.

Possible values for the humanReadable flag:

• None: If you don’t pass the flag, all field values will be returned in machine-format.
• "APPEND": Include supported human-readable fields in the response as an additional part of the response JSON. When using this mode fields that do not have an actual value ('null' fields) will return in the machine-format only.
• "REPLACE": Return only human-readable values. When using this mode fields that do not have an actual value ('null' fields) will not return at all.

📘

Notes:

1. Null fields will not be returned: The human-readable values will be returned only for fields that have an actual value (are not 'null' ). This means that if you attempt to retrieve only the human-readable values, you may not receive all the requested fields in the response. To retrieve all fields, make sure to use the APPEND option, which will always retrieve the machine-readable values as well.
2. Custom field ID: Field ids that include a custom list item will not convert the list item within the field id. For example: payroll.entitlement.261867508.amountwhen converted to human-readable will return this way:
   • "payroll": {
     "entitlement": { "261867508": { // not converted to human-readable "amount": "$32.00" // converted to human-readable }}}

Example response with humanReadable = "APPEND":

{
    "/root/creationDate": {										// all fields are in machine format
        "value": "2019-09-08"
    },
    "fullName": "Alan Tullins",
    "creationDate": "2019-09-08",
    "work": {
        "department": "209192163"
    },
    "/root/fullName": {
        "value": "Alan Tullins"
    },
    "/work/department": {
        "value": "209192163" 										
    },
    "humanReadable": {													// human readable section
        "fullName": "Alan Tullins",
        "creationDate": "08/09/2019",
        "work": {
            "department": "Account Receivables" 
        }
    },
    "id": "2128438031986721630"
}

Lists

Fields can be linked to a list. Lists hold string item values that can be selected for the field.

Lists can be out-of-the-box or custom (defined by the user) and can be one of the following types:

• list - a collection of list items.
• multi-list - a collection of lists.
• hierarchy-list - a collection of lists with levels.

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

When reading fields of type 'list', 'multi-list', and 'hierarchy-list', the API returns the list item's ID rather than the value displayed in the UI by default.

For example:

{
  "work": {
    "department": "209192163"		// the numeric ID of the item in the Departments list
  }
}
{
  "work": {
    "department": "Animals"		// the string ID of the item in the Departments list
  }
}

The ID may be a string (if this is an out-of-the-box list item) or a numerical ID (for custom list items that the user added). In both cases, you need to convert this ID to a "human-readable " format in order to see the item's display value.

To convert the ID to the display value, you can:

1. Use metadata: Read the list's metadata and find the relevant item. To learn more, see 'Get all company lists' metadata
2. Use a flag: Use the 'employee search' endpoint to use a flag that will automatically return the display value. To learn more, see Converting list items using a flag

Note: You should always retrieve the display value which represents how the list item appears in the UI, because even when the ID is a string that seems like the display value, it may have been renamed, and will have a different display value. For example, the "Animals" list item was rename to "Pets":

JSON

{
	"id": "Animals",			// original out-of-the-box ID
	"value": "Pets",			// renamed display value
	"name": "Pets",
	"archived": false,
	"children": []
},

Converting list items using a flag

Some endpoints support a shortcut of fetching the human-readable value of a list item using the humanReadable flag. This is support when calling the Search for employees endpoint and other People data endpoints. Using this flag, you can retrieve the human-readable values of the list while querying the data, rather than calling the metadata endpoint and retrieving the list values.

To learn more, see Human-readable values.

Employee data metadata endpoints

'Get all employee fields' metadata endpoint

To find out the properties of fields, you should call the Get all employee fields metadata endpoint:

GET https://api.hibob.com/v1/company/people/fields

Response:

{
       "id": "work.department",	// Field ID
       "category": "work",	// Field Category
       "name": "Department",
       "description": null,
       "jsonPath": "work.department",
       "type": "list",	// Field Type
       "typeData": {
           "listId": "department" // use this to read the list metadata
},
"historical": true
}

📘

Category name

The category returned in the field properties contains the category ID. It may look something like 'workContact' or 'work' if this is an out-of-the-box category or something like 'category_1720508362305' for custom categories. To obtain the category name as it appears in Bob's UI, you can view the category in the UI and see the category ID as part of the URL: https://app.hibob.com/employee-profile/3332883884017717778#category_1720508362305

'Get all company lists' metadata

This endpoint returns lists and their values. So, when you read a field containing a list item backend ID, you should use this endpoint to fetch the item's display value.

1. Follow the steps in Get all employee fields to get the field's metadata.
2. Locate the field ID and check the metadata.
3. If the field's type is list, multi list or hierarchical list, use Get all company lists endpoint to get the list values, and pass the field name in the listName parameter.

Example:

   {
        "id": "work.department",
        "category": "work",
        "name": "Department",
        "description": null,
        "jsonPath": "work.department",
        "type": "list",
        "typeData": {
            "listId": "department"
        },
        "historical": true
    },

• Field ID: "work.department"
• List ID: typeData > "list" > listId > "department"
• Get the list's values:

GET https://api.hibob.com/v1/company/named-lists/department 

4. Locate the items' backend ID in the response and fetch the the display value from the value property:

    "department": {
        "name": "department",
        "values": [
            {
                "id": "209192143",							// list item ID
                "value": "Account Management",	// Human readable (display) value
                "name": "Account Management",
                "archived": false,
                "children": []
            }
        ],