Bob's Job Catalog 2.0 is a database that details the hierarchy of all the jobs in your organization.

📘

Note:

The new job catalog API is available only for users working with the new Job catalog 2.0, currently open only to new customers and customers who had not used the job catalog before February 9, 2025. To learn more, see Getting started with the new job catalog ↗.

What’s new:

• Job profile search: Filter job profiles by status, job family group, job family, and job role for targeted reporting and integration.
• Job catalog settings: Access detailed metadata for job profiles, job family groups, job families, and job roles, including available fields and custom attributes.
• Job content library: Retrieve complete lists of job family groups, job families, and job roles to get a comprehensive view of your catalog.

Additional resources

• Explore Job Catalog API.
• Job profiles API reference guide.
• Job catalog settings API reference guide.
• Job content library API reference guide.

The Org Level is a new field in the employee data that provides information about the employee's organizational level. It is a read-only calculated field provided by Bob. To learn more about the Org level field, see People's data fields glossary ↗.

Using the Public API you can:

1. Read the Org Level of an employee: use the Search for employees endpoint and specify the field id: employee.orgLevel. Make sure to grant the service user permissions to view the Work category.

POST https://api.hibob.com/v1/people/3332883955555522'
{
	"showInactive": false,
	"fields": [
    "employee.orgLevel"
	]
}

2. Read the possible values for this field: use the Get all company lists endpoint with the list ID: orgLevels.

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

Two new properties were added to the Get all employee fields (metadata) endpoint to facilitate finding a field's category in Bob's UI. Nothing has changed in the existing properties.

The new properties are:

• categoryDisplayName: How the category appears in Bob's UI. Use this property to identify the category when setting permissions to the service user. To learn more, see Permissions.
• categoryId: The backend-id of the category (it is the same as the existing category property added for additional clarity). It can be either text-based (for out-of-the-box categories) or numeric. It does not represent how the category appears in Bob's UI.

Example

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

With the February release, we've updated the /timeoff/requests/changes endpoint.

The 'changes' endpoint retrieves all the time off requests activity based on the date the change has occurred.

What's new?

1. The endpoint was renamed to 'Get time off request changes': The endpoint's title was renamed from the old "Get all new/deleted time off requests since the specified date" to better reflect the endpoint's action.
2. Query now limited to 6 months: The since query param now supports retrieving time off request changes that occurred up to 6 months back.
3. A new optional 'to' query param:
   • A new to query param was added to this endpoint, which together with the since param allows to specify a date range.
   • This is an optional parameter. If not specified, the query will include results up to the current date.
   • You can use the date range to retrieve changes older than 6 months.
     For example since:2024-01-01T14:30:24.345Z, to:2024-06-30T14:30:24.345Z
   • The date range is limited to 6 months. A date range longer than 6 months will fail.

To learn more, see Get time off request changes.

In Bob, when the date or time of a Time off request is changed (a "hard update"), the existing request is replaced with a new one. Modification history, from the original request to the latest, is visible in Bob:

History tracking via the API

Two new properties are being added to improve history tracking via the API:

• originalRequestId: The ID of the very first request before any modifications were made.
• previousRequestId: The ID of the most recently replaced request.

What has changed?

On the February 18, 2025 release, we have fixed issues in the Time off update webhook event and the Get Time off request details endpoint:

• Time off API:
  Previously, previousRequestId incorrectly referred to the first request ID. Now, both originalRequestId and previousRequestId are returned with the correct values.
• Time off webhook event:
  • Previously, originalRequestId incorrectly referred to the latest request ID. Now, both properties are included with accurate values.
  • The getUrl previously incorrectly referred to the previous request ID. Now, it will refer to the latest request ID.

Impact on You

This fix affects you if:

• You use the Time off update webhook event or the Get Time off request details endpoint.
• You rely on previousRequestId or originalRequestId.

If both apply, update your code to handle these properties correctly.

What's next

Review the relevant documentation:

• Get the details of an existing time off request.
• Time off webhooks events:
  • Time off events v2
  • Time off events v1

We've implemented several updates to improve the accuracy and usability of our API documentation based on feedback received through the Bob developer hub voting and feedback option.

How can you send us feedback

We appreciate your feedback. Keep voting on issues and add your suggestions to the Bob developer hub! 🚀

What's new?

New use-case: How to read the employee status

We've added a new example showing how to read the employee status (Active, Inactive) and the lifecycle status (Hired, Employed, Terminated, Garden leave, Leave, Parental leave).

The example includes which fields you should retrieve and which permissions should be added to the service user.

To learn how to do this, see How to read employee status.

Resolved recursive array issue in list metadata responses

• This fix ensures the list metadata response is correctly structured in the developer hub's example, improving consistency and better aligning with the expected payload.
• It also resolved an issue affecting developers using npx api with the Node testing option to interact with this endpoint.

Improved Create new custom table entry request example

The Request Example option now provides an enhanced structure that better aligns with the expected payload. Still, we recommend using tools like Postman for more complex payloads.

Bob webhooks v2 is now available for use. It adds reliability and stability by reducing the data sent on the payload, ensuring the events will be sent in the correct order, and providing a better retry mechanism when a webhook fails to send the event.

What's new?

• We’ve made some structure changes to the payload format, and the payload now focus on metadata. Detailed data should be retrieved using Bob's API.
• We've revised the delivery mechanism and added email notifications in case of delivery errors. You can now set up the appropriate people to receive these notifications to address any issues proactively.

How does this affect me?

• No immediate action is required for organizations using Bob webhooks.
• When adding a webhook, you can choose between v2 (default) and v1.
• Webhooks v2 and v1 will run in parallel for now.
• For better reliability and stability, we recommend using Webhooks v2 for current and future integrations.

What's the timeline?

• Starting January 21, 2025, you can create v2 webhooks in Bob's UI.
• New v1 webhooks can still be created until April 1, 2025.
• From April 1, 2025, creating new v1 webhooks will no longer be possible.
• Existing v1 webhooks will continue to run alongside v2, but only v2 webhooks can be created after this date.
• Advance notice will be provided before any future deprecation of v1 functionality to ensure a smooth transition.

🚧

Deprecation notice:

Starting April 1, 2025, you will no longer be able to create new v1 webhooks in Bob's UI. We recommend reviewing the documentation and considering using v2 for your existing and future developments.

To learn more, see Migrate to webhooks V2.

The 'Get all new/deleted time off requests since the specified date' endpoint now includes two new properties. These properties improve tracking when a request’s date or time is updated, creating a new time-off request record:

• originalRequestId: Containing the backend-id of the very first time-off request. It remains unchanged regardless of updates that create new time off request records. It serves as the anchor for tracing the request's entire history back to its initial submission.
• previousRequestId: Containing the backend-id of the previous request that was replaced when this new request was created.

To learn more, see Time off API.

The Bob developer hub website has been enhanced to provide developers with a more intuitive experience and valuable resources.

Here’s a summary of the updates:

• Redesigned homepage: The homepage has been updated with a clean, modern design to improve navigation and usability.
• New Explore by Module section:
  • This section introduces high-level articles for each API module, explaining how it aligns with Bob's concepts and detailing the available endpoints.
  • The Explore People API article describes the employee data model and field types, complemented by intuitive diagrams and tables that help developers understand how different types of data are represented in Bob and accessed through the Public API.
• Expanded tutorials: New step-by-step tutorials are now available to help developers get started with features like the People Search API, Webhooks.
• Reorganized API Reference : The endpoints are now grouped by module (e.g., Employee data, Reports, Docs) for easier navigation.

These updates aim to improve the developer experience and provide better support for integrating with Bob’s platform.

In the coming December release, the employee data will include a new Ethnicities field reflecting a new employee profile field in Bob.

Why this change?

With the introduction of the new Ethnicities list field, employees can now select multiple races instead of being limited to a single option. This new field is also available through the public API.

What is being changed?

The current Ethnicity field (eeo.ethnicity) will remain available for use with Bob’s Search for employees public API for another six months, alongside the new Ethnicities field (employee.ethnicities).

To fetch the old and new field properties, use the Field Metadata endpoint.

Timeline of Changes

• December 17, 2024: new Ethnicities field will be introduced.
  • If you use the API to retrieve values from the old Ethnicity field, the returned value will be sourced from the new Ethnicities field.
  • If you use the API to update values in the old Ethnicity field, those values will be automatically copied to the new Ethnicities field.
• June, 2025: old ethnicities field will be deprecated.
  • If you will use the old ethnicities field in your APIs you will get an error.

❗️

Deprecation notice for the current Ethnicity field

Developers will have until June 2025 to adjust their APIs to use the new ethnicities field when pulling data and updating it.

To learn more about the new ethnicities field, see this post in Bob's Heartcore HR Community.