---
updatedAt: 2026-05-14T07:34:10.000Z
---

Fetch the complete documentation index at: https://apidocs.hibob.com/llms.txt. Use this file to discover all available pages before exploring further.

# Explore Workforce planning API

Understand the basic concepts of workforce planning in Bob and how to utilize it with the Public API

## Overview

The Workforce Planning module in Bob allows you to plan your staffing needs and provides visibility into your current and future workforce.

The Workforce Planning API provides developers with robust tools to access positions, position openings, and budgets programmatically. It enables seamless integration with solutions like ATS (Applicant Tracking Systems) to track vacancies and FP\&A (Financial Planning and Analysis) tools to plan budgets for current and future workforce needs.

> 📘 Note:
>
> If you have not purchased Workforce planning, you will not have access to this feature. To learn more, see <a href="https://www.hibob.com/features/workforce-planning">Workforce planning ↗</a>.

To learn more about workforce planning in Bob, see <a href="https://help.hibob.com/hc/en-us/articles/9268066931345" target="_blank">Getting started with Workforce planning ↗</a>.

## Key concepts

<Accordion title="Positions" icon="fa-info-circle">
  Positions are a core entity of the Workforce Planning (WFP) module, enabling you to allocate budgets and assign specific roles to positions for your workforce's current and future needs. Roles are defined in the Job Catalog, and positions are created to fulfill these roles.

  A position’s status can be: `filled`, `starting` (Filled soon), `vacant`, `onHold` (On hold), `departing` (Vacant soon),  `cancelledSoon` (Cancelled soon) or `cancelled` (Cancelled). Each position includes various attributes such as department, site, employment type, and manager.

  Each position is linked to:

  * <b>Position openings</b>. Position openings are created within the positions, and each position must have at least one opening.
  * <b>Job profile</b>. Each position must be linked to a specific job which is taken from the Job Catalog.
  * <b>Budget (cost)</b>. The budget for the position is optional and it is created within the position. Budgets can be accessed only with the appropriate permissions.

  To learn more about the position fields and statuses, see the <a href="https://help.hibob.com/hc/en-us/articles/9566016131217" target="_blank">Workforce planning glossary ↗</a>.
</Accordion>

<Accordion title="Position openings" icon="fa-info-circle">
  Position openings are always linked to a Position in Bob. They allow organizations to plan multiple hiring scenarios under the same position, such as maternity leave replacements or organizational growth, without duplicating positions. Each opening can have its recruitment status, expected start date, and opening name.

  To learn more, see <a href="https://help.hibob.com/hc/en-us/articles/9268685085713#h_01H95VEXGESVX6BXFEVGQTGSMM" target="_blank">Position management ↗</a>.
</Accordion>

<Accordion title="Position budgets" icon="fa-info-circle">
  Position budgets are available only if you <b>activate the position cost feature</b> in the workforce planning settings.
  Budgets are always linked to a Position in Bob. They allow tracking of the financial allocation for specific roles within the organization. Budget attributes include the budget date which marks when the funding starts for the position, currency, base salary, and variable pay.

  To learn more, see <a href="https://help.hibob.com/hc/en-us/articles/15302770733585" target="_blank">Set up position costs ↗</a>.
</Accordion>

<Accordion title="Jobs and the Job Catalog" icon="fa-info-circle">
  A company’s Job Catalog lists all available jobs and their details. Positions must be linked to jobs to ensure consistent role definitions.

  There are two versions of the Job Catalog in Bob, and the API supports them differently:

  * <b>New Job Catalog 2.0</b>: This version is fully supported by the API. You can create, read, update, and delete positions. The API also allows you to retrieve all job profile details using the Job Catalog API endpoints.
    * <b>Old Job Catalog</b>: This version is supported in read-only mode. You can retrieve the job name linked to a position, but you cannot access detailed job information or perform create, update, or delete operations on positions via the API.

  > <b>Note</b>: Position create, update, and delete actions are only supported when using the new Job Catalog 2.0. If you're using the old catalog, you'll need to migrate to the new version to access the full capabilities of the Workforce Planning API.
</Accordion>

## Required permissions

Before accessing position data, ensure the service user has permission to access the relevant information, just as you would when assigning permissions to a user in Bob.

See [Workforce planning API Reference](https://apidocs.hibob.com/reference/workforce-planning#permissions-required).

## Workforce Planning endpoints

The Workforce Planning API provides functionality to access positions, position openings, and position budgets:

<Table align={["left","left","left"]}>
  <thead>
    <tr>
      <th>
        Use Case
      </th>

      <th>
        Public API Endpoint
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        Read Metadata
      </td>

      <td>
        [Get all positions fields](https://apidocs.hibob.com/reference/get_metadata-objects-position)

        [Get all positions openings fields  ](https://apidocs.hibob.com/reference/get_positions-position-openings-metadata)

        [Get all position budget fields](https://apidocs.hibob.com/reference/get_positions-position-budget-metadata)
      </td>

      <td>
        Get a list of all fields related to positions, position openings or budgets.
      </td>
    </tr>

    <tr>
      <td>
        Read Positions
      </td>

      <td>
        [Read company positions](https://apidocs.hibob.com/reference/post_objects-position-search)
      </td>

      <td>
        Retrieve positions filtered by attributes like status or site or fetch details for a specific position
      </td>
    </tr>

    <tr>
      <td>
        Read Position opening
      </td>

      <td>
        [Read company positions openings](https://apidocs.hibob.com/reference/post_positions-position-openings-search)
      </td>

      <td>
        Retrieve position openings filtered by recruitment status or start date
      </td>
    </tr>

    <tr>
      <td>
        Read Position Budget
      </td>

      <td>
        [Read company positions budgets](https://apidocs.hibob.com/reference/post_positions-position-budget-search)
      </td>

      <td>
        Retrieve position budget data for specific departments or roles
      </td>
    </tr>

    <tr>
      <td>
        Create and update Position (i)
      </td>

      <td>
        [Create position](https://apidocs.hibob.com/reference/post_workforce-planning-positions)

        [Update position](https://apidocs.hibob.com/reference/patch_workforce-planning-positions-positionid)

        [Cancel position](https://apidocs.hibob.com/reference/patch_workforce-planning-positions-positionid-cancel)

        [Schedule Positions Cancellation](https://apidocs.hibob.com/reference/post_workforce-planning-positions-schedule-cancellation)
      </td>

      <td>
        * When creating a Position, the position opening is mandatory.
        * Position budget is optional and will be created only if the service user has the required permission..
        * Currently, you cannot create position requests that require an approval flow, which are not supported via the API.
      </td>
    </tr>

    <tr>
      <td>
        Create and update Position Opening (i)
      </td>

      <td>
        [Create position opening](https://apidocs.hibob.com/reference/post_workforce-planning-positions-positionid-position-openings)

        [Update position opening](https://apidocs.hibob.com/reference/patch_workforce-planning-positions-positionid-position-openings-positionopeningid)

        [Delete position opening](https://apidocs.hibob.com/reference/delete_workforce-planning-positions-positionid-position-openings-positionopeningid)
      </td>

      <td>
        Allows the creation of additional openings on an existing position and updates existing ones.
      </td>
    </tr>

    <tr>
      <td>
        Create and update the position budget (i)
      </td>

      <td>
        [Update position budget](https://apidocs.hibob.com/reference/patch_workforce-planning-positions-positionid-position-budget-positionbudgetid)   
        [Create position budget](https://apidocs.hibob.com/reference/post_workforce-planning-positions-positionid-position-budget) 
      </td>

      <td>
        Allows for updating an existing budget for a position.
      </td>
    </tr>
  </tbody>
</Table>

<Callout icon="ℹ️" theme="info">
  The write and update endpoints are designed using our new [object-based structure](https://apidocs.hibob.com/reference/object-based-endpoints) and standardized API methodology, part of our broader effort to make Bob’s APIs more consistent, predictable, and easier to work with across different domains.
</Callout>

To learn more, see the [Workforce Planning API reference](https://apidocs.hibob.com/reference/workforce-planning).

## Workforce Planning webhooks

Bob allows you to subscribe to system events by providing a Webhook URL as a listener. When an event occurs, Bob will call this listener and send details in the event's payload.

The workforce planning webhooks enable you to receive notifications whenever positions or data related to positions are updated.

Each Webhook event sends information specific to the event, and the listener can then make an API call to retrieve additional data as needed for further context.

Workforce planning events include:

* Position Created
* Position Updated
* Position Opening Created
* Position Opening Updated
* Position Opening Deleted
* Position Budget Created
* Position Budget Updated

**Notes:**

1. Budgets and position openings are always associated with a specific position.
2. Position opening events don’t include the position ID, but you can get it by retrieving the opening details.
3. Budget events do include the position ID, because budget details don’t return it.

To learn more, see [Workforce planning events](https://apidocs.hibob.com/reference/workforce-planning-webhooks).

## API Workflows

**A typical workflow for using this API may include the following steps:**

<Accordion title="1. Fetch Values Before Creating a Position" icon="fa-database">
  Before creating a position, you'll need to fetch details which are required in order to create a position:

  * Job profile from the [Job Catalog API](https://apidocs.hibob.com/reference/job-catalog)
  * List values for department, site, and employment type via the [Named Lists API](https://apidocs.hibob.com/reference/get_company-named-lists-listname)
</Accordion>

<Accordion title="2. Create Position" icon="fa-plus-square">
  Use the `POST /workforce-planning/positions` endpoint.

  You must include:

  * Job profile ID (see Step 1 above)
  * Position opening (required)
  * Budget (optional)
</Accordion>

<Accordion title="3. Update Position" icon="fa-edit">
  Use the `PATCH /workforce-planning/positions/{positionId}` endpoint to:

  * Change effective date, site, or job profile
  * Adjust for updates from FP\&A
</Accordion>

<Accordion title="4. Add/Update Position Opening" icon="fa-user-plus">
  A position opening is always linked to a position, so you must have the position ID in order to update the openings. You can:

  * Add position openings using: `POST /positions/{positionId}/position-openings`
  * Update existing openings using: `PATCH /positions/{positionId}/position-openings/{openingId}`
</Accordion>

<Accordion title="5. Update Position Budget" icon="fa-dollar-sign">
  the budget is always linked to a position, however, you don't have to provide the position ID in order to update the budget. This way you can
  Use `PATCH /positions/position-budgets/{budgetId}` if salary or currency needs to be updated.
</Accordion>

<Accordion title="6. Search and Report" icon="fa-search">
  Use the following endpoints to fetch and filter data:

  * `POST /objects/position/search`
  * `POST /positions/position-openings/search`
  * `POST /positions/position-budget/search`
</Accordion>

<Accordion title="7. (Optional) Use Webhooks" icon="fa-bell">
  Subscribe to events to trigger downstream systems (like ATS or FP\&A):

  * Position Created / Updated
  * Opening Created / Updated / Deleted
  * Budget Created / Updated
</Accordion>

### Common use cases

The Workforce planning API can be used for the following scenarios:

1. **Trigger ATS job openings from Position updates in Bob using webhooks** If Bob’s Workforce Planning (WFP) module is your source of truth for position data, you can use webhooks to keep your ATS in sync. For example, when a position is created or its recruitment status changes to "Open", a webhook can notify your system to automatically create a corresponding job opening in the ATS. This helps ensure hiring starts at the right time and reduces manual work.
2. **Integrate your FP\&A solution:**
   * **Create positions after budget approval from FP\&A** When the FP\&A team finalizes budgets, you can create corresponding positions in Bob using the API. Call the Create Position endpoint to define the department, site, employment type, and role (from the job catalog), add a position opening, and include the budget in the request. This enables automated, accurate workforce planning once financial approvals are granted.
   * **Update positions after changes in FP\&A** If the FP\&A team modifies properties like job seniority or location (which affects cost planning), you use the Update Position endpoint to sync site, seniority, or employment type, and adjust the budget or expected start date as needed
3. **Poll on vacant position openings** When using an external hiring system, which is not part of Bob, use the API to retrieve a filtered list of vacant position openings to include them in your hiring process, ensuring timely hiring.
4. **Plan workforce changes** Read open positions and link the data to BI systems to enhance insight by data.
5. **Budget planning and alignment** Access position budget data to align workforce planning with financial forecasting.

### Best practices

1. **Permission Configuration**
   * Ensure the API Service user has permissions under: `System Settings > Account > Permission Groups > Workforce Planning`
   * Verify the Service user has access to:
     * View, edit, and create positions.
     * Manage budget and recruitment statuses. To learn more, see <a href="https://help.hibob.com/hc/en-us/articles/9268353757713" target="_blank">Set up permissions for Workforce planning  ↗</a>.
2. **Use the human-readable flag** Each property can be returned from the API as a backend-id value or as a human-readable string, which is how it will look like in Bob’s UI. Use the `humanReadable `flag to include both representations for more clarity.
3. **How to fetch position budgets** Budgets are linked to positions, so you first need to fetch the position with the `budget` field, which holds the budget backend ID, and then query the budget details using the ID.

   For detailed endpoint descriptions and examples, see the [Workforce planning API Reference](https://apidocs.hibob.com/reference/workforce-planning).

<br />