# Developer Docs Documentation ## Guides - [Employee tables and custom tables](https://apidocs.hibob.com/docs/additional-employee-data.md): Learn how to retrieve employee data stored in tables - [Categories and permissions](https://apidocs.hibob.com/docs/categories-and-permissions.md): Understand how to set service user permissions to fields and categories - [Create an employee](https://apidocs.hibob.com/docs/create-employee.md): Learn how to update employee data fields using Bob’s API - [Fields and lists metadata](https://apidocs.hibob.com/docs/fields-metadata.md): Learn how to use field metadata to efficiently extract and manage field data. - [Read employee data](https://apidocs.hibob.com/docs/how-to-read-employee-data.md): Learn how to retrieve and process employee data using Bob’s API - [Update employee data](https://apidocs.hibob.com/docs/update-employee-data.md): Learn how to update employee data fields using Bob’s API - [Explore Attendance API](https://apidocs.hibob.com/docs/explore-attendance-api.md): Understand the basic concepts of attendance entries in Bob - [Explore Docs API](https://apidocs.hibob.com/docs/explore-docs-api.md): Understand the basic concepts of Documents in Bob and how you can access them via the Docs Public API - [Explore Employee data API](https://apidocs.hibob.com/docs/explore-employee-data.md): Understand the basic concepts of employee data API in Bob - [Explore Goals API](https://apidocs.hibob.com/docs/explore-goals-api.md): Understand the basic concepts of Goals in Bob and how to utilize them with the Public API - [Explore Job catalog API](https://apidocs.hibob.com/docs/explore-job-catalog-api.md): Understand the basic concepts of Job catalog in Bob and how to utilize it with the Public API - [Explore Reports API](https://apidocs.hibob.com/docs/explore-reports.md): Understand the basic concepts of Reports and how you can access them via the Public API - [Explore Tasks API](https://apidocs.hibob.com/docs/explore-tasks.md): Understand the basic concepts of Tasks and how you can access them via the Public API - [Explore Time off API](https://apidocs.hibob.com/docs/explore-time-off-api.md): Understand the basic concepts of time off requests and policies in Bob - [Explore Workforce planning API](https://apidocs.hibob.com/docs/explore-workforce-planning.md): Understand the basic concepts of workforce planning in Bob and how to utilize it with the Public API - [API Service users](https://apidocs.hibob.com/docs/api-service-users.md): Use service users to authenticate API calls to Bob - [API Terms of Use](https://apidocs.hibob.com/docs/api-terms-of-use.md) - [Getting started with Bob's API](https://apidocs.hibob.com/docs/getting-started.md) - [HiBob MCP integration (Beta)](https://apidocs.hibob.com/docs/bob-mcp-integration-beta.md): This feature is in beta and may change as we continue to improve it. - [Integrate with ATS (Hire API)](https://apidocs.hibob.com/docs/how-to-integrate-with-ats-hire-api.md): How to develop an integration with Applicant Tracking Systems (ATS) and push new hires into Bob seamlessly - [Working with employee search](https://apidocs.hibob.com/docs/how-to-read-employee-data-tutorial.md): Step-by-step tutorial for using the employee Search endpoint to retrieve employee data - [Integrate with your Careers page](https://apidocs.hibob.com/docs/how-to-use-hiring-api-careers-page.md): Use Bob's Hiring API to integrate with your external careers page directly from Bob Hiring - [Working patterns in the Public API](https://apidocs.hibob.com/docs/how-to-work-with-working-patterns.md): Learn how to fetch and process an employee's working patterns using the Public API - [Migrate to Webhooks V2](https://apidocs.hibob.com/docs/migrate-to-webhooks-v2.md): Learn how to smoothly migrate from Webhooks V1 to Webhooks V2 - [Transition from API Access tokens](https://apidocs.hibob.com/docs/transition-from-api-access-tokens.md): Learn how to transition from API Access Token to Service User ## API Reference - [Attendance](https://apidocs.hibob.com/reference/attendance.md): Use the API to import attendance entries to Bob - [Import attendance data](https://apidocs.hibob.com/reference/post_attendance-import-importmethod.md):

This endpoint allows you to import attendance punches (entries) for employees.

Before using this endpoint:

- [Get time off requests changes](https://apidocs.hibob.com/reference/get_timeoff-requests-changes.md): Returns an array of all changes made to time off requests within a specified date range. Each item in the array includes: the time off request details at the time of the change, and the type of change, such as `created` or `deleted`. Optionally, requests that were changed to status `pending` can also be included.

**Notes:**


**Permissions required**: Please refer to the main Time off API Required Permissions page. - [Read a list of who's out of the office.](https://apidocs.hibob.com/reference/get_timeoff-whosout.md): Returns time off information for a given date range, only for the users the Service User can access.

Possible time off request types:
days is when the request is for X days.
hours is when the request is for X hours during the day requested (supported only for policy types measured in hours).
portionOnRange is when the request is for every morning or every afternoon during the days requested.
hoursOnRange is when the request is for X hours every day during the days requested.
differentDayDurations is when the request is for a different amount of hours on each of the days requested.
specificHoursDayDurations is when the request is for specific hours per day.
differentSpecificHoursDayDurations is when the request is for different specific hours or portions on each day.
percentageOnRange is when the request is for X percent of every day during the days requested.
openEnded is when the request doesn't have an end date yet.

Each request type is represented with a separate schema with the relevant fields.

**Please note:**
- [Time off](https://apidocs.hibob.com/reference/time-off.md): The Time off API provides access to the details of your company time off requests and policies. - [Submit a new time off request.](https://apidocs.hibob.com/reference/post_timeoff-employees-id-requests.md): Submits a new time off request.

Time off requests can be of the listed types in the body params section below.

Each request type requires different parameters in the body params. Select the type in the body params section to view the expected fields.

**Testing Note:**
To test each type of request:
1. Open the relevant request type in the body params section.
2. In the test widget on the right, click "Request Example" to open the menu, and select the request type you want to send.
3. Update values and send.

**Important testing disclaimer:** Changing the request type example does not automatically switch the parameters. First, select the request schema, and then select the equivalent request in the "Request Example" to avoid inconsistencies in the example fields. - [API calls for webhook v2 events](https://apidocs.hibob.com/reference/api-calls-for-webhook-events.md): API calls examples to retrieve the data relevant to webhook events - [Docs events](https://apidocs.hibob.com/reference/docs-events-v2.md) - [Employee events](https://apidocs.hibob.com/reference/employee-events-v2.md): The following events can be used to create Employee data updates Webhooks. - [Getting started with Webhooks](https://apidocs.hibob.com/reference/getting-started-webhooks.md): Learn how to subscribe to events in Bob and be notified whenever a change occurs. - [Task events](https://apidocs.hibob.com/reference/task-events-v2.md): Receive notifications about triggered task lists and tasks status updates. - [Time off events](https://apidocs.hibob.com/reference/time-off-events-v2.md): The following events can be used to create Time off request Webhooks. - [Workforce planning events](https://apidocs.hibob.com/reference/workforce-planning-events.md): The following events can be used to create Workforce Planning webhooks. - [Employee events (v1 Legacy)](https://apidocs.hibob.com/reference/employee-changes-events.md): The following events can be used to create Employee data updates Webhooks. - [Task events (v1 Legacy)](https://apidocs.hibob.com/reference/employee-task-events.md): Receive notifications about triggered task lists and tasks status updates. - [eSign events (v1 Legacy)](https://apidocs.hibob.com/reference/esign-document-signing-event.md) - [[ Legacy] Webhooks v1](https://apidocs.hibob.com/reference/webhook-events-v1.md) - [Time off events (v1 Legacy)](https://apidocs.hibob.com/reference/time-off-webhook-events.md): The following events can be used to create Time off request Webhooks. - [Deletes Position Opening](https://apidocs.hibob.com/reference/delete_workforce-planning-positions-positionid-position-openings-positionopeningid.md): Deletes a position opening - [Get all positions fields](https://apidocs.hibob.com/reference/get_metadata-objects-position.md): Returns a list of all fields of object type position.
- [Get all position budget fields](https://apidocs.hibob.com/reference/get_positions-position-budget-metadata.md): Returns a list of all fields of object type position budget.
- [Get all positions openings fields](https://apidocs.hibob.com/reference/get_positions-position-openings-metadata.md): Returns a list of all fields of object type position opening.
- [Workforce Planning](https://apidocs.hibob.com/reference/workforce-planning.md): The Workforce Planning API provides access to positions in your company. - [Cancel Position](https://apidocs.hibob.com/reference/patch_workforce-planning-positions-positionid-cancel.md):

Immediately cancels a position and updates its status to cancelled.

Important: This operation will fail if the position is currently filled (i.e., employees are still assigned to its openings).

To cancel filled positions, use the Schedule Positions Cancellation endpoint, which automatically unassigns employees before cancelling the position.

- [Update Position Budget](https://apidocs.hibob.com/reference/patch_workforce-planning-positions-positionid-position-budget-positionbudgetid.md): Updates a specific position budget within a position - [Update Position Opening](https://apidocs.hibob.com/reference/patch_workforce-planning-positions-positionid-position-openings-positionopeningid.md): Updates a specific position opening within a position **Notes:**
- For fields that require reference to a list in Bob, use the metadata endpoint to fetch list values.
- [Update Position](https://apidocs.hibob.com/reference/patch_workforce-planning-positions-positionid.md): Updates an existing position **Notes:**
- Currently, you cannot use approval flows, which are not supported via the API.
- This endpoint requires linking the position to a job profile, and can be used only with Job Catalog 2.0. To retrieve the `jobProfile`, use the Job Catalog API.
- For fields that require reference to a list in Bob (e.g. `department`), use the metadata endpoint to fetch list values.
- [Read company positions](https://apidocs.hibob.com/reference/post_objects-position-search.md): This endpoint returns a list of company positions filtered by the specified attributes. Note that this endpoint requires body parameters, which is why it is implemented as a POST request.



**Required permissions**
To access the positions, the service user making the call must have the following permissions:
**Features > Workforce planning > Position management > Manage positions**.
- [Read company positions budgets](https://apidocs.hibob.com/reference/post_positions-position-budget-search.md): This endpoint returns a list of company positions budgets filtered by the specified attributes. Note that this endpoint requires body parameters, which is why it is implemented as a POST request.

The required body parameters are:
- **Fields**: Specify the fields you want to retrieve. A list of available fields can be found in the 200 response body detailed below.
- **Filters**: Define the filtering conditions. You can filter by the fields defined in the filter section.
- **Pagination**: This endpoint uses cursor-based pagination to handle large number of table entries. To learn more, see Pagination in Bob's API


**Required permissions**
To access the positions, the service user making the call must have the following permissions:
**Features > Workforce planning > Position management > Manage positions**.
- [Read company positions openings](https://apidocs.hibob.com/reference/post_positions-position-openings-search.md): This endpoint returns a list of company positions openings filtered by the specified attributes. Note that this endpoint requires body parameters, which is why it is implemented as a POST request.

The required body parameters are:
- **Fields**: Specify the fields you want to retrieve. A list of available fields can be found in the 200 response body detailed below.
- **Filters**: Define the filtering conditions. You can filter by the fields defined in the filter section.
- **Pagination**: This endpoint uses cursor-based pagination to handle large number of table entries. To learn more, see Pagination in Bob's API


**Required permissions**
To access the positions, the service user making the call must have the following permissions:
**Features > Workforce planning > Position management > Manage positions**.
- [Create Position Budget](https://apidocs.hibob.com/reference/post_workforce-planning-positions-positionid-position-budget.md): Creates a specific position budget within a position **Limitations:**
- You can create up to 1 budget per request.
- If the request includes more than 1 budget, the operation will fail and return an error.

- [Create Position Opening](https://apidocs.hibob.com/reference/post_workforce-planning-positions-positionid-position-openings.md): Creates a new position opening within a position

**Limitations:**
- You can create up to 10 position openings per request.
- If the request includes more than 10 position openings, the operation will fail and return an error.

**Notes:**
- For fields that require reference to a list in Bob, use the metadata endpoint to fetch list values.
- [Schedule Positions Cancellation](https://apidocs.hibob.com/reference/post_workforce-planning-positions-schedule-cancellation.md):

Schedules the cancellation of one or more positions. This endpoint automatically unassigns any employees connected to the position openings before cancellation.

Note:

Limitations:

- [Create Position](https://apidocs.hibob.com/reference/post_workforce-planning-positions.md): Creates new positions with associated position opening and optional position budget.

**Limitations:**
- You can create up to 10 positions per request.
- If the request includes more than 10 positions, the operation will fail and return an error.

**Notes:**
- 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.
- The endpoint will return the ID of the positions and the position opening that were created. To find out the budget ID you should read the position details.
- Currently, you cannot create "position requests" that require an approval flow, which are not supported via the API.
- This endpoint requires linking the position to a job profile, and can be used only with Job Catalog 2.0. To retrieve the `jobProfile`, use the Job Catalog API.
- For fields that require reference to a list in Bob (e.g. `department`), use the metadata endpoint to fetch list values.
## Pages - [API Changes & Deprecations](https://apidocs.hibob.com/api-changes-deprecations.md) ## Changelog - [Hiring API: Job ad site and workspace type added](https://apidocs.hibob.com/changelog/hiring-api-accurate-job-ad-location-and-work-details.md) - [Time off API: Added policy assignment status to balance](https://apidocs.hibob.com/changelog/time-off-api-added-assignment-status-to-balance.md) - [Goals API: Check-in audit notes](https://apidocs.hibob.com/changelog/goals-api-check-in-audit-notes-update.md) - [Attendance Projects API: Now available](https://apidocs.hibob.com/changelog/attendance-projects-api-now-available.md) - [Goals API: Added support for goal cycles](https://apidocs.hibob.com/changelog/goals-api-added-support-for-goal-cycles-and-weights.md)