Employee data API: Field level permissions

Overview

HiBob’s new field-level permissions model gives customers more flexibility and control when granting Public API access to employee data. This update enables access management for each individual field, rather than only at the category level.

What’s changing

From category-level to field-level permissions

Previously, permissions were granted at the category level (e.g., Work, Personal, About). To access a single field, developers had to request access to the entire category.

Now, each field has its own permission settings. Although category permissions still exist, the fields inherit or override them. You can open access to just the fields your integration needs, without exposing the whole category.

Customers will be prompted to choose permission behavior when adding or moving fields between categories.

“People” becomes “People’s Fields”

The former People permission section is now called People’s fields, reflecting its new scope and structure within People’s Data.

​​Sensitive field logic is being adjusted to behave like other fields

Previously, some fields' permissions (e.g., SSN, full date of birth, age) were enforced with hard-coded logic that required both View and Edit permissions to be visible via API. This was done to ensure categories with sensitive fields will be treated with extra care.

Now that you can set the permissions per field, this logic is being removed.

During migration, the field permissions will be adjusted to maintain the previous behavior.

• If your service user previously had View and Edit permissions for these fields, they will automatically maintain this access.
• If it had View but not Edit, these sensitive fields will now have no access, maintaining previous behavior.

See more details in migration behavior.

How field-level permissions work

• Categories still exist, but as containers. Categories still organize fields, but permissions now apply to each field individually. Category-level permissions continue to exist, but now they act as defaults or inheritance points for the fields inside them.
• You can now open a field without opening a category. Allow access to a single field even when the rest of its category should remain restricted. For example: You can permit access only to Work > Working location, while keeping the rest of the Work category closed. This allows integrations to target only the data they actually need.
• New logic when fields move between categories. When a field is moved to another category, Bob Admins are prompted to choose:
  • Set the field’s permissions to No access by default
  • Inherit the new category’s permissions (previous behavior)
    This prevents unintentional permission side effects when reorganizing fields.

Detecting restricted columns in API responses

When the service user has partial column permissions, employee table endpoints return
metadata indicating which columns were filtered from the response.

Response metadata

When columns are restricted, the API response includes:

• restricted_columns object in the JSON body
• X-Has-Restricted-Columns: true HTTP header

This helps you distinguish between:

• A field that genuinely has no value (returns null)
• A field that was filtered due to missing permissions (listed in restricted_columns)

Example response

{
  "values": [
    {
      "id": 1,
      "effectiveDate": "2024-01-15",
      "title": "Software Engineer",
      "department": null,
      "reportsTo": null
    }
  ],
  "restricted_columns": {
    "no_view_permission": ["salaryPayType", "fte"],
    "no_view_history_permission": ["department", "reportsTo"]
  }
}

Restricted column categories

Affected endpoints

This metadata appears in GET responses for employee table endpoints:

Single-employee table endpoints:

• /v1/people/{id}/work
• /v1/people/{id}/employment
• /v1/people/{id}/salaries
• /v1/people/{id}/lifecycle
• /v1/people/{id}/training
• /v1/people/{id}/equities
• /v1/people/{id}/variable
• /v1/people/{id}/bank-accounts
• /v1/people/custom-tables/{employeeId}/{tableId}

Bulk table endpoints:

• /v1/bulk/people/work
• /v1/bulk/people/employment
• /v1/bulk/people/salaries
• /v1/bulk/people/lifecycle

Best practices

• Check for the X-Has-Restricted-Columns header to quickly detect if any columns were filtered
• If you need specific column values, ensure the service user has explicit View permission for those fields
• Handle restricted columns gracefully in your integration logic

How does it affect existing integrations

With field-level permissions enabled, access to employee fields is now governed at two levels:

• Category-level: If a category is open, all fields in it are accessible unless field-level overrides restrict them.
• Field-level: Customers can explicitly open or restrict individual fields, even if the category is closed.

Together, these determine what the service user can read or update.

Practical examples

Migration behavior

During migration to the new model:

• Permissions for employee fields will be listed under People’s data > People’s fields (previously "People").
• Existing category-level permissions are automatically converted to equivalent field-level permissions.
• Sensitive fields migrate as follows:
  • If the service user had Edit, they keep access.
  • If they had only View, the field will now have no access until explicitly granted.

    🚧

    Note: The automatic migration ensures the behavior aligns with the intent of the previous setup and prevents the exposure of sensitive data without explicit permission.

Action items for partners

1. Update your integration setup instructions.
   We recommend simplifying customer setup to use only the fields you need, not entire categories.
   • Instead of: People’s data > People > About > View selected employees’ About sections
   • Use: People’s data > People’s fields > About > Email > View
2. Update sensitive fields instructions. If you only need View permission to sensitive fields, remove instructions that instruct customers to grant Edit access to these fields. Edit is no longer required to view these values. You should instruct them to explicitly set View permission to this field instead.
3. We recommend testing and validating:
   • POST /people/search
   • POST /people/{identifier}
   • Any Custom Table or Employee Table endpoints
   • All custom fields you retrieve
   • Any sensitive fields you currently expect in responses
4. Before rollout:
   • Confirm which fields your integration needs access to.
   • Check whether any sensitive fields need to be added to your setup.
   • Update your permission instructions to specify exact fields.
   • Test your integration’s installation and onboarding flow with the new model.
   • Share feedback with our team to finalize the model.

Availability

The field-level permissions feature is being rolled out gradually to customers starting in February 2025.
Access is gated behind a toggle and may be enabled on a per-account basis during the rollout.

FAQs

Do I need to update my integration now?
Not immediately. Category permissions still work, but we recommend narrowing them to field-level access for the least privilege and a smoother customer setup.

Do I need to update my integration documentation now?
Yes. Although category-level permissions can still be applied in your instructions, you may want to narrow it down to only the fields you actually use in your integration. Also, the instructions for setting category-level permissions have been changed because they now reside in a new “People’s fields” section.

Will any fields stop returning values because of this change?
Not automatically. However, if customers adjust permissions or move fields, a field may become restricted. Integrations should handle missing fields gracefully.

Can I request access to just one field instead of a whole category?
Yes. Field-level permissions allow fine-grained access for exactly the fields you depend on.

What happened to SSN, DOB, and other sensitive fields?
They now follow standard field-level rules. Edit is no longer required for read access.

How can I check what permissions a field requires?
Use the GET /company/people/fields endpoint to retrieve field IDs and categories, then confirm with the customer that the service user’s group has access to this field.