In Bob, employee fields are systematically organized within categories. These categories are the primary unit for assigning permissions, meaning that permissions are always assigned to categories rather than individual fields.

Each category is identified by a unique category ID, which varies between out-of-the-box categories and user-defined categories:

• Out-of-the-box category IDs: these IDs may appear as strings, such as 'work.' Renaming the category does not change its ID.
• User-defined category IDs: these IDs follow a specific format, such as category_1720508362305.

📘

Field IDs and Categories

Field IDs may look like they include the category (e.g., "work.department"), but you should not rely on this format. If you move a field to another category the ID doesn't change. Always check the field’s category using the metadata instead of looking at the field's ID. To learn more about setting permissions for fields that have been moved to a different category, see Moving fields between categories.

Find the category in Bob's UI

When identifying a field’s category in Bob’s UI, always use the categoryDisplayName property from the field’s metadata instead of relying on the field ID or category ID.

Out-of-the-box/renamed category:

Consider the following metadata:

{
        "id": "root.firstName",
        "categoryId": "root",
        "categoryDisplayName": "Basic info",
        "category": "root",
        "name": "First name",
        "description": null,
        "jsonPath": "firstName",
        "type": "text",
        "typeData": {},
        "historical": false
    }

• The field ID (id) is root.firstName.
• The categoryId is root.
• However, the actual category name, as displayed in Bob’s U,I is Basic info, which is found in the categoryDisplayName property.

This means that even if the category ID suggests a different name, you should always reference categoryDisplayName to ensure consistency with what users see in the UI.

Custom field example:

Consider the following metadata:

{
        "id": "custom.category_1720508362305.field_1720508402110",
        "categoryId": "category_1720508362305",
        "categoryDisplayName": "Customized category",
        "category": "category_1720508362305",
        "name": "Custom field in custom category",
        "description": null,
        "jsonPath": "custom.category_1720508362305.field_1720508402110",
        "type": "text",
        "typeData": {},
        "historical": false
    }

• The category ID is category_1720508362305.
• However, the actual category name, as displayed in Bob’s UI, is Customized category, which is found in the categoryDisplayName property.

How to see the category ID in Bob's UI

If you do need to locate the category ID in Bob's UI, you can find int in the URL:

• The out-of-the-box category would look something like this:
  app.hibob.com/employee-profile/3332883884017714448#financial
• The custom category would look something like this:
  app.hibob.com/employee-profile/3332883884017714448#category_1720508362305

Setting permissions to categories

The Public API permissions are enabled with the same logic as the permission you enable for other users on the platform and are based on field categories. Only categories that the service user can access are included in the response.

This means that when you enable permissions to the Service User, you enable the permission to the category and, as a result, to all the fields that reside in that category.

Note: Although a Bob Admin can move fields between categories, for some fields this may affect platform behavior and other features in Bob, so before doing so it is best to ensure where else you're using the specific field across the platform. To learn more, see Set up People's data fields ↗.

📘

Setting permissions

To learn how to set up a service user with permissions, see API Service Users.

Example:
If the service user doesn’t have permission to access the Work category, the data returned will not include fields placed under the work category.

To allow the service user to access work data or other categories, you should add to the service user’s permission group the relevant permissions:

👍

Good to know!

Explore the Permission groups (FAQs, use cases, and more) ↗ in the The HiBob Community (for Bob admins) where you can find answers to questions like:

• How to pull custom fields from a table via API ↗
• Getting custom fields via API endpoint Search for employees ↗

Finding the right permission

When setting permissions, the category name in the UI may be different from the category ID, for example if you rename the category. For example, if the 'address' category was renamed to 'Address with Custom' in the UI, when setting permissions, you should look for 'Address with Custom'.

Moving fields between categories

Bob Admins can move fields to different categories. When this happens, the field will not be accessible unless you have granted access to the new category. If you can't retrieve an employee's field through the API, please check that it is still located in the category you're trying to access.

👍

Note:

If you use the People Search endpiont without specifying specific fields, this will read only the predefined default categories. The quickest solution is to move the field back to its original location.

Otherwise, you may need to perform a different query type, specifying the field ID you're trying to access, such as "root.id." Please note that the field ID does not change when moving between categories—you can always find the field ID using the fields metadata endpoint. To learn more, see Call search API.

Setting permissions for sensitive user data

Fields that are considered sensitive data, such as an employee’s year of birth, require an extra layer of security. This means that you may not be able to see these fields with the permissions given to the service user.

Year of birth

To access the users' complete date of birth, including the year, you must ensure that the service user has both View and Edit permissions in the People’s Data > People > Personal permissions category.

SSN

To access the users' SSN, you must ensure the service user has both View and Edit permissions in the People’s Data > People > Identification permissions category.

To learn more about service user permissions, see API Service Users.
To learn more about the different employee fields in Bob, see People's data fields glossary ↗.