In Bob, employee data fields are organized within categories. With field-level permissions, you can grant access at the category level (as a default for fields in that category) or at the individual field level. Permissions for employee fields are configured under People’s data > People’s fields.

Category types

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.

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", // use this
        "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 UI 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 (People’s fields)

The Public API permissions follow the same model as permissions for other users on the platform. Employee field permissions live under People’s data > People’s fields.

You can grant access:

• At category level — opens the fields in that category (subject to any field-level overrides).
• At field level — opens only the specific fields your integration needs, even if the rest of the category stays restricted.

Only fields the service user can access are included in API responses. Prefer granting the minimum fields required.

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

Example:
If the service user doesn’t have permission to the Work category or to specific Work fields, the data returned will not include those fields.

To allow the service user to access work data, add the relevant permissions under People’s data > People’s fields. In the People’s fields table:

• View and Edit can be set on the category row or on specific fields.
• View history can be set only on the category row (not per field).

For least privilege, grant View / Edit only on the fields you need (for example Work > Department > View), and enable View history on the category only when your integration reads historical table rows.

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 under People’s fields, you should look for 'Address with Custom'.

Moving fields between categories

Bob Admins can move fields to different categories. When a field is moved, Bob Admins are prompted to choose whether the field should get No access by default or inherit the new category’s permissions. If you can't retrieve an employee's field through the API, check the field’s current category in metadata and confirm the service user has View (and Edit, if required) on that field or category under People’s fields.

Setting permissions for sensitive user data

Fields that are considered sensitive data, such as an employee’s year of birth or SSN, require an extra layer of security. Hard-coded logic still requires both View and Edit on these fields for them to be returned via the API. Field-level permissions do not remove this requirement — you can grant access to the individual field under People’s fields, but both View and Edit must be enabled.

Year of birth

To access the users' complete date of birth (birthDate), including the year, ensure the service user has both View and Edit on the date of birth field under People’s data > People’s fields > Personal (or the category where the field currently resides).

SSN

To access the users' SSN, ensure the service user has both View and Edit on the SSN field under People’s data > People’s fields > Identification (or the category where the field currently resides).

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