Workforce Planning API now supports the new Job Catalog 2.0.

What's new?

The Workforce Planning API now reflects the structure of the new Job Catalog 2.0, where positions are linked to job profiles instead of job levels.

When retrieving a position's job via the API:

  • /position/jobProfile:
    • New field that returns the job profile assigned to the position.
    • Available only for customers using Job Catalog 2.0.
    • Use it to fetch full job details via the Job Catalog API.
  • /position/job:
    • Previously returned a job level.
    • For customers on Job Catalog 2.0, this now returns the job profile for backward compatibility.
    • ⚠️ This field will be deprecated in the future. Update your integrations to use jobProfile.

To learn more, see Read company positions.

Who does this affect?

This change applies to any customer using Job Catalog 2.0:

  • You did not use the old Job Catalog before February 9, 2025, or
  • You've migrated from the old catalog to version 2.0.

To learn more, see Getting started with the new job catalog ↗.

Migration notes

If you've migrated to the Job Catalog 2.0 ↗:

  • The job level previously stored in /position/job now returns the job profile.
  • The job profile includes level, title, and additional metadata.
  • The human-readable label remains familiar: e.g., "Lead (3) Account Executive (J-6329338628)"
  • The /position/job field continues to work for now, but should be replaced with jobProfile in your code.
🚧

Deprecation note:

The /position/job field will be deprecated in the future. We recommend switching to jobProfile in your integrations as soon as possible.

Workforce Planning now supports prorated position costs. When you define your fiscal year and add an end date to a position, the platform automatically calculates the cost based on how long the position is active during that financial cycle.

You can now access these details through the Public API:

  • The /position/endEffectiveDate field is available on the position object. It indicates when the position’s cost should stop being included in planning.
  • The /position/positionBudget/proRatedCostCurrencyValue field is available on the position budget. It shows the calculated prorated cost of the position, converted to your company’s base currency.

This gives you API visibility into how position costs are prorated, helping you align external reports or tools with your workforce planning data.

To learn more, see Read company positions, and Read company position budgets.

We’re experimenting with short audio recaps and deep dives to make our documentation more accessible. The first ones are live at the end of the article:

Each provides a quick, AI-generated summary that highlights the main points.

We're curious if this format is useful to you, so feel free to share feedback via the vote option at the bottom of the article (and please include your email so we can follow up!).

Following past deprecation announcements:

These are now being completely shut down.

❗️

Final Notice: API Get Endpoints Shutdown by May 6, 2025

The Get endpoints listed below will be completely shut off by May 6, 2025.

  • GET api.hibob.com/v1/people
  • GET api.hibob.com/v1/people/XXXX

If your organization is still using the deprecated endpoints, action is required to prevent disruptions. Any processes relying on these endpoints will stop working, potentially impacting your operations. Follow the instructions below to migrate to the new Search API to replace the two GET endpoints.

❗️

Final Notice: API Access Tokens Shutdown by May 6, 2025

The "API Access Token" authentication method will be completly shut off by May 6, 2025.

Companies using this legacy method should transition to the Service User method immediately. From this date, API integrations using API Access Tokens will stop working. Any system or process that relies on API Access Tokens will fail, potentially causing disruptions.

Follow the instructions to transition to the API Service Users authentication method.

We’ve enabled two AI-friendly features to support AI tools in parsing and interacting with our docs:

  • llms.txt file – A dedicated file that's now available on our website. Give it to AI tools like ChatGPT or Claude and ask it questions about our API. It will help them to better understand and navigate our API docs and provide better answers.
  • AI Dropdown – You’ll now see a new dropdown on every article page with options to:
    • Ask ChatGPT or Claude about the article
    • Copy the page as Markdown
    • View it in plain Markdown

These updates are especially helpful if you use AI to summarize or extract content, or when you need to access machine-readable versions of our docs.


You can now download API audit logs to monitor usage of Bob’s public API. Logs include request metadata such as timestamp, endpoint, method, status code, service user ID, and query parameters.

You can access the API audit logs from Bob's System settings > Account > API audit.

What's new?

  1. We've added source_ip column to each log entry for improved traceability and security auditing.
  2. You can allow users who are not Admins to download API audit logs.by granting them the following permission: Features > Settings > Audit > Read and download company Audit data.

To learn more, see API audit logs.

The createdOn timestamp is now included in the response payload for the following endpoints:

This field indicates when each request was created.

Note that you could already filter requests using the since and to query parameters — which refer to the request's creation date. With this update, the same creation date is returned in the response (createdOn), giving you clearer visibility into the data you're querying.

📘 The documentation has been updated accordingly.

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

To learn more, see Explore Job Catalog API.

Additional resources

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"
	]
}
  1. 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