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 ↗.

Metadata endpoints

The metadata endpoints provide access to fields and list properties.

To learn more, see Metadata endpoints.

Field 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 category of the field is how you grant access to the service user. The 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

You can find out the field’s id using the field’s metadata:
For example: "id": "work.department"

A field ID can be represented in 2 ways:

• work.department
• /work/department

Both ways are valid:

fields": [
    "/root/id",									
    "/work/department"
  ],

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

Note: Field ids in a response with data will always contain the “/” notation:

employee:{      
	"/root/id": {				
    			"value": "3332883884017713938"
 		},
	"/work/department": {	
       "value": "Account Receivables"
}

Custom fields

Employee data may include custom fields defined by the user. When reading the default employee data it does not include the custom fields. You should read these fields explicitly by mentioning their ID in the fields parameter when calling the search endpoint.

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
    }

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.

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": []
            }
        ],