Explore Workforce planning 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 Workforce planning ↗.

To learn more about workforce planning in Bob, see Getting started with Workforce planning ↗.

Key concepts

Positions

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), or canceled. Each position includes various attributes such as department, site, employment type, and manager.

Each position is linked to:

Position openings. Position openings are created within the positions, and each position must have at least one opening.
Job profile. Each position must be linked to a specific job which is taken from the Job Catalog.
Budget (cost). 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, see the Workforce planning glossary ↗.

Position openings

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

Position budgets

Position budgets are available only if you activate the position cost feature in the workforce plannings 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 Set up position costs ↗.

Jobs and the Job Catalog

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:

New Job Catalog 2.0: 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.
- Old Job Catalog: 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.

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

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.

Workforce Planning endpoints

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

Use Case	Public API Endpoint	Description
Read Metadata	Get all positions fields Get all positions openings fields Get all position budget fields	Get a list of all fields related to positions, position openings or budgets.
Read Positions	Read company positions	Retrieve positions filtered by attributes like status or site or fetch details for a specific position
Read Position opening	Read company positions openings	Retrieve position openings filtered by recruitment status or start date
Read Position Budget	Read company positions budgets	Retrieve position budget data for specific departments or roles
Create and update Position (i)	Create position Update position Cancel position	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.
Create and update Position Opening (i)	Create position opening Update position opening Cancel position opening	Allows the creation of additional openings on an existing position and updates existing ones.
Update the position budget (i)	Update position budget	Allows for updating an existing budget for a position.

ℹ️
The write and update endpoints are designed using our new object-based structure 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.

To learn more, see the Workforce Planning API reference.

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:

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

To learn more, see Workforce planning events.

API Workflows

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

1. Fetch Values Before Creating a Position

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
List values for department, site, and employment type via the Named Lists API

2. Create Position

Use the POST /workforce-planning/positions endpoint.

You must include:

Job profile ID (see Step 1 above)
Position opening (required)
Budget (optional)

3. Update Position

Use the PATCH /workforce-planning/positions/{positionId} endpoint to:

Change effective date, site, or job profile
Adjust for updates from FP&A

4. Add/Update Position Opening

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}

5. Update Position Budget

the bugdet is always linked to a postiion, 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.

6. Search and Report

Use the following endpoints to fetch and filter data:

POST /objects/position/search
POST /positions/position-openings/search
POST /positions/position-budget/search

7. (Optional) Use Webhooks

Subscribe to events to trigger downstream systems (like ATS or FP&A):

Position Created / Updated
Opening Created / Updated / Deleted
Budget Created / Updated

Common use cases

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

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.
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
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.
Plan workforce changes Read open positions and link the data to BI systems to enhance insight by data.
Budget planning and alignment Access position budget data to align workforce planning with financial forecasting.

Best practices

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 Set up permissions for Workforce planning ↗.
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.
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.