# Bob Developer Hub Documentation ## Guides - [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 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) - [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 endpoint](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 - [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 - [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 ## API Reference - [Get the details of a single job ad](https://apidocs.hibob.com/reference/get_hiring-job-ads-id.md): Returns the details of the job ad that was promoted on the Bob careers page.

To learn more about the Hiring API and how to integrate with your career page, see How to integrate with your careers page - [Hiring](https://apidocs.hibob.com/reference/hiring.md): Bob's Hiring API allows you to fetch job ads from Bob's careers page and post them to your custom careers page - [Get all active job ads from your Career page](https://apidocs.hibob.com/reference/post_hiring-job-ads-search.md): Returns an array of active job ads as promoted on the Bob career page.

To learn more about the Hiring API and how to integrate with your career page, see How to integrate with your careers page - [Authorization](https://apidocs.hibob.com/reference/authorization.md): How to build the authorization header when sending HTTP calls to Bob. - [Pagination](https://apidocs.hibob.com/reference/pagination-1.md): Bob offers cursor-based pagination for some of our API’s collection endpoints. - [Permissions](https://apidocs.hibob.com/reference/permissions.md): Learn about setting service user permissions to access the data in Bob - [Rate limiting](https://apidocs.hibob.com/reference/rate-limiting.md): Rate limits are restrictions that our API imposes on the number of times a user can access our endpoints within a specified period of time. - [Testing](https://apidocs.hibob.com/reference/testing.md): Learn how to test endpoints using your own data - [Delete a Document from a Confidential Folder](https://apidocs.hibob.com/reference/delete_docs-people-id-confidential-docid.md): Use this endpoint to delete a specific document from a confidential folder of a specific employee in Bob.

Make sure you set the right permissions to the Service User in order to remove the file. See more details in How to set up permissions for People's Docs . - [Delete a Document from a Custom Folder](https://apidocs.hibob.com/reference/delete_docs-people-id-folders-folderid-docid.md): Use this endpoint to delete a specific document from a custom folder of a specific employee in Bob.

Make sure you set the right permissions to the Service User in order to remove the file. See more details in How to set up permissions for People's Docs . - [Delete a Document from a Shared Folder](https://apidocs.hibob.com/reference/delete_docs-people-id-shared-docid.md): Use this endpoint to delete a specific document from a shared folder of a specific employee in Bob.

Make sure you set the right permissions to the Service User in order to remove the file. See more details in How to set up permissions for People's Docs . - [Get list of folders with metadata](https://apidocs.hibob.com/reference/get_docs-folders-metadata.md): Use this endpoint to get the a list of available folders and their metadata, including the folder ID. Use the ID when uploading a file to a specific folder. - [Download list of documents of an employee](https://apidocs.hibob.com/reference/get_docs-people-id.md): Returns a list of documents and download links.
- [Documents](https://apidocs.hibob.com/reference/documents.md): The Docs API provides access to the details of your company documents and folders. - [Upload File to a Confidential Folder](https://apidocs.hibob.com/reference/post_docs-people-id-confidential-upload.md): Use this endpoint to upload a file directly into a confidential folder of a specific employee in Bob.

Make sure you set the right permissions to the Service User in order to upload the file. See more details in How to set up permissions for People's Docs . - [Upload file from a URL to a Confidential Folder](https://apidocs.hibob.com/reference/post_docs-people-id-confidential.md): Use this endpoint to upload a file from a specified URL directly into a confidential folder of a specific employee in Bob.

Make sure you set the right permissions to the Service User in order to upload the file. See more details in How to set up permissions for People's Docs . - [Upload File from a URL to a Custom Folder](https://apidocs.hibob.com/reference/post_docs-people-id-custom-folderid.md): Use this endpoint to upload a file from a specified URL directly into a specific custom folder of a specific employee in Bob.

Make sure you set the right permissions to the Service User in order to upload the file. See more details in How to set up permissions for People's Docs . - [Upload File to a Custom Folder](https://apidocs.hibob.com/reference/post_docs-people-id-folders-folderid-upload.md): Use this endpoint to upload a file directly into a custom folder of a specific employee in Bob.

Make sure you set the right permissions to the Service User in order to upload the file. See more details in How to set up permissions for People's Docs . - [Upload file to a Shared Folder](https://apidocs.hibob.com/reference/post_docs-people-id-shared-upload.md): Use this endpoint to upload a file directly into a shared folder of a specific employee in Bob.

Make sure you set the right permissions to the Service User in order to upload the file. See more details in How to set up permissions for People's Docs . - [Upload file from a URL to a Shared Folder](https://apidocs.hibob.com/reference/post_docs-people-id-shared.md): Use this endpoint to upload a file from a specified URL directly into a shared folder of a specific employee in Bob.

Make sure you set the right permissions to the Service User in order to upload the file. See more details in How to set up permissions for People's Docs . - [Delete custom table entry](https://apidocs.hibob.com/reference/delete_people-custom-tables-employee-id-custom-table-id-entry-id.md) - [Read all entries of the given custom table](https://apidocs.hibob.com/reference/get_people-custom-tables-employee-id-custom-table-id.md) - [Read metadata for specific custom table](https://apidocs.hibob.com/reference/get_people-custom-tables-metadata-custom-table-id.md) - [Read metadata of custom tables defined](https://apidocs.hibob.com/reference/get_people-custom-tables-metadata.md) - [Custom Tables](https://apidocs.hibob.com/reference/custom-tables.md): The Custom Tables API provides access to the details of your company employees's custom tables. - [Create new custom table entry](https://apidocs.hibob.com/reference/post_people-custom-tables-employee-id-custom-table-id.md): Provide an array of columns and their values.
Values can be any of the supported field types.

**Note**: You can use **Examples > Request Example** option for a basic example, however, we recommend that you copy the endpoint to Postman and test more complicated structures using the JSON editor. - [Update custom table entry](https://apidocs.hibob.com/reference/put_people-custom-tables-employee-id-custom-table-id-entry-id.md) - [Deletes a bank account entry from a given employee's bank accounts table.](https://apidocs.hibob.com/reference/delete_people-id-bank-accounts-entry-id.md) - [Deletes an employment entry from a given employee's employment history.](https://apidocs.hibob.com/reference/delete_people-id-employment-entry-id.md) - [Deletes an equity grant for an employee.](https://apidocs.hibob.com/reference/delete_people-id-equities-entry-id.md) - [Deletes a salary entry from the employee's list.](https://apidocs.hibob.com/reference/delete_people-id-salaries-entry-id.md) - [Deletes any training records for an employee.](https://apidocs.hibob.com/reference/delete_people-id-training-entry-id.md) - [Deletes a variable payment record for an employee.](https://apidocs.hibob.com/reference/delete_people-id-variable-entry-id.md) - [Deletes a work entry from a given employee's work history.](https://apidocs.hibob.com/reference/delete_people-id-work-entry-id.md) - [List employment history for a list of employees.](https://apidocs.hibob.com/reference/get_bulk-people-employment.md):

Returns a list of historical employment entries from the employment table for all employees or a specific list of employees.

Each employment entry includes the working pattern assigned to this employee. To learn more about working patterns, see How to work with Working patterns.

Required permissions

In order to access the employment history of each requested employee, the service user making the call must have the following permissions:

  • For the employment table: People's Data > Employment > View all other employees' Employment section histories.
  • For the employees: People's Data > Access data for: Make sure the employees are in the list. Employees that are not listed and were specifically requested will be listed under `errors` in the response.

    • Pagination

    This endpoint uses cursor-based pagination to handle large number of table entries. To learn more, see Pagination in Bob's API.

    - [List the lifecycle history for a list of employees.](https://apidocs.hibob.com/reference/get_bulk-people-lifecycle.md): Returns a list of historical lifecycle entries from the lifecycle table for all employees or a specific list of employees.

    **Required permissions**
    In order to access the lifecycle history of each requested employee, the service user making the call must have the following permissions:
    **For the work table**: People's Data > Lifecycle > View all other employees' Lifecycle section histories.
    **For the employees**: People's Data > Access data for > Make sure the employees are in the list. Employees that are not listed and were specifically requested will be listed under `errors` in the response.
    **Pagination**
    This endpoint uses cursor-based pagination to handle large number of table entries. To learn more, see Pagination in Bob's API - [List payroll history (salaries) for a list of employees.](https://apidocs.hibob.com/reference/get_bulk-people-salaries.md): Returns a list of historical salary entries from the payroll table for all employees or a specific list of employees.

    **Required permissions**
    In order to access the payroll history of each requested employee, the service user making the call must have the following permissions:
    **For the salary table**: People's Data > Payroll > View all other employees' Payroll section histories.
    **For the employees**: People's Data > Access data for > Make sure the employees are in the list. Employees that are not listed and were specifically requested will be listed under `errors` in the response.
    **Pagination**
    This endpoint uses cursor-based pagination to handle large number of table entries. To learn more, see Pagination in Bob's API - [List work history for a list of employees](https://apidocs.hibob.com/reference/get_bulk-people-work.md): Returns a list of historical work entries from the work table for all employees or a specific list of employees.

    **Required permissions**
    In order to access the work history of each requested employee, the service user making the call must have the following permissions:
    **For the work table**: People's Data > Work > View all other employees' Work section histories.
    **For the employees**: People's Data > Access data for > Make sure the employees are in the list. Employees that are not listed and were specifically requested will be listed under `errors` in the response.

    **Pagination**
    This endpoint uses cursor-based pagination to handle large number of table entries. To learn more, see Pagination in Bob's API - [Read payroll tables history.](https://apidocs.hibob.com/reference/get_payroll-history.md): Note: This endpoint is maintained for legacy purposes but is planned for deprecation in the future. We recommend using alternative employee table endpoints where possible. - [List employee's bank accounts](https://apidocs.hibob.com/reference/get_people-id-bank-accounts.md):

    Returns a list of the bank accounts table entries for a given employee.

    Note: The Bank Account details are listed under the 'Financial' category in Bob's UI. They include basic bank account details, and may include also a list of bank accounts (if using more than a single bank account). This endpoint will fetch only the list of bank accounts.

    To fetch the basic bank account details (not the table), use the employee's search endpoint instead, and specify the fields you want to fetch (e.g. 'financial.bankName'). To learn more, see how to work with Fields, Custom fields and Lists.

    See the '200' response for the body response. - [List employee's employment history.](https://apidocs.hibob.com/reference/get_people-id-employment.md):

    Returns a list of employment history entries for a given employee.

    Each employment entry includes the working pattern assigned to this employee. To learn more about working patterns, see How to work with Working patterns.

    Required permissions

    In order to access the employment history of each requested employee, the service user making the call must have the following permissions: People's Data > Employment > View all other employees' Employment section histories.

    - [List the employee's equity grants.](https://apidocs.hibob.com/reference/get_people-id-equities.md): Returns a list of equity grants for a given employee. - [List employee's lifecycle status history.](https://apidocs.hibob.com/reference/get_people-id-lifecycle.md): Returns a list of historical lifecycle entries from the lifecycle table for an employee.

    **Required permissions**
    In order to access the lifecycle history, the service user making the call must have the following permissions:
    **For the lifecycle table**: People's Data > Lifecycle > View all other employees' Lifecycle section histories.
    **For the employees**: People's Data > Access data for > Make sure the employee is in the list. - [List employee's salary history.](https://apidocs.hibob.com/reference/get_people-id-salaries.md): Returns a list of historical salary entries from the salary table in the payroll section for an employee.

    **Required permissions**
    In order to access the payroll history, the service user making the call must have the following permissions:
    **For the salary table**: People's Data > Payroll > View all other employees' Payroll section histories.
    **For the employee**: People's Data > Access data for > Make sure the employee is in the list. - [List the employee's training records.](https://apidocs.hibob.com/reference/get_people-id-training.md): Returns a list of training entries from the employee's Training table, for a given employee. - [List employee's variable payments](https://apidocs.hibob.com/reference/get_people-id-variable.md): Returns a list of variable payments for a given employee.

    **Required permissions**
    In order to access the work history, the service user making the call must have the following permissions:
    **For the work table**: People's Data > Work > View all other employees' Work section histories.
    **For the employee**: People's Data > Access data for > Make sure the employee is in the list.

    - [Employee Tables](https://apidocs.hibob.com/reference/employee-tables.md): The Employee Tables API provides access to the details of your company employees's data tables. - [Search for actual payments](https://apidocs.hibob.com/reference/post_people-actual-payments-search.md): This endpoint allows you to search for actual payments based on various filters.

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

    In order to access the actual payments history of each requested employee, the service user making the call must have this permission: People's Data > Payroll > View selected employees' Payroll sections

    **Testing notes**:

    1. Use the testing widget's **Try It!** option to test this endpoint.
    2. Request Example: Use the **Examples > Request example** option to see how to initiate body parameters.
    3. Response Example: View the response payload using the **Response > Response example** option in the response on the right. - [Create a new bank account entry for a given employee.](https://apidocs.hibob.com/reference/post_people-id-bank-accounts.md) - [Creates a new employment entry for a given employee.](https://apidocs.hibob.com/reference/post_people-id-employment.md):

    Note: The values of the list fields represent the list item ID and not the list item value. To obtain the corresponding list item value, use the HiBob metadata API to determine the field list name. Then, use the list item ID to locate the list item value. For more information, see How to work with lists Public API. - [Creates a new equity grant for a given employee.](https://apidocs.hibob.com/reference/post_people-id-equities.md):

    Note: The values of the list fields represent the list item ID and not the list item value. To obtain the corresponding list item value, use the HiBob metadata API to determine the field list name. Then, use the list item ID to locate the list item value. For more information, see How to work with lists Public API. - [Creates a new salary entry for a given employee.](https://apidocs.hibob.com/reference/post_people-id-salaries.md):

    Note: The values of the list fields represent the list item ID and not the list item value. To obtain the corresponding list item value, use the HiBob metadata API to determine the field list name. Then, use the list item ID to locate the list item value. For more information, see How to work with lists Public API. - [Creates a new training records for a given employee](https://apidocs.hibob.com/reference/post_people-id-training.md): Create a new training record in the Training table. Follow the parameters description for more details on the values to pass to this endpoint. - [Creates a new variable payment for a given employee.](https://apidocs.hibob.com/reference/post_people-id-variable.md):

    Note:The values of the list fields represent the list item ID and not the list item value. To obtain the corresponding list item value, use the HiBob metadata API to determine the field list name. Then, use the list item ID to locate the list item value. For more information, see How to work with lists Public API. - [Create a new work entry for a given employee.](https://apidocs.hibob.com/reference/post_people-id-work.md):

    Note: The values of the list fields represent the list item ID and not the list item value. To obtain the corresponding list item value, use the HiBob metadata API to determine the field list name. Then, use the list item ID to locate the list item value. For more information, see How to work with lists Public API. - [Update a bank account entry in the employee's bank accounts table.](https://apidocs.hibob.com/reference/put_people-id-bank-accounts-entry-id.md): This endpoint updates an entry in the employee’s Bank accounts table.
    The unique identifier for the bank account entry is the entry id. To obtain the employee's bank account entries use the GET /people/{employee-id}/bank-accounts endpoint.

    **Notes**:
    1. **Out-of-the-box columns**: These columns will be completely overwritten with the data provided in your payload. Any columns not included in the payload will be cleared (set to empty values). 2. **Custom columns**: These columns will remain unchanged unless explicitly included in the payload.

    - [Update an employment entry from a given employee's employment history.](https://apidocs.hibob.com/reference/put_people-id-employment-entry-id.md): This endpoint updates an entry in the employee’s employment history table.

    Note that the entire employnebt entry will be overwritten with the data provided in your payload. Any columns not included in the payload will be cleared (set to empty values).

    - [Updates an equity grant for an employee](https://apidocs.hibob.com/reference/put_people-id-equities-entry-id.md): This endpoint updates an entry in the employee’s equity table.

    Note that the entire equities entry will be overwritten with the data provided in your payload. Any columns not included in the payload will be cleared (set to empty values).

    - [Update a work entry in the employee's work history table.](https://apidocs.hibob.com/reference/put_people-id-work-entry-id.md): This endpoint updates an entry in the employee’s work history table.
    The unique identifier for the work entry is the site and effective date.

    Note that the entire work entry will be overwritten with the data provided in your payload. Any columns not included in the payload will be cleared (set to empty values).

    Patch Update Flag:
    As a best practice, we recommend reading the entire work entry data, updating the necessary fields, and then writing back the entire entry. However, for legacy purposes, we provide the flag: patchUpdate=true, which functions similarly to a PATCH request.
    When using this flag, please note:
    1. Only the fields included in the payload will be updated; all others will remain unchanged.
    2. The identifier for the work entry should be entry_id, not the site/effective date.
    3. Note that using the patchUpdate approach is not recommended and should be reserved for legacy implementations only. - [Delete an item from an existing list.](https://apidocs.hibob.com/reference/delete_company-named-lists-listname-itemid.md) - [Delete an existing field.](https://apidocs.hibob.com/reference/delete_company-people-fields-fieldid.md) - [Get a specific company list by name.](https://apidocs.hibob.com/reference/get_company-named-lists-listname.md) - [Get all company lists](https://apidocs.hibob.com/reference/get_company-named-lists.md) - [Get all employee fields.](https://apidocs.hibob.com/reference/get_company-people-fields.md): This endpoint retrieves only metadata about the employee fields and includes all employee fields. Calling this endpoint does not require any permissions for the service user performing this action.

    However, fetching the actual data requires setting the relevant permissions for the service user, including permissions to access employee data and relevant categories.
    To learn more, see Search for employees . - [Metadata](https://apidocs.hibob.com/reference/metadata.md): The Matadata API provides access to the details of your company resources. - [Add a new item to an existing list.](https://apidocs.hibob.com/reference/post_company-named-lists-listname.md) - [Create a new field.](https://apidocs.hibob.com/reference/post_company-people-fields.md) - [Update an existing item from a list.](https://apidocs.hibob.com/reference/put_company-named-lists-listname-itemid.md) - [Update an existing field](https://apidocs.hibob.com/reference/put_company-people-fields-fieldid.md) - [Get a summary of all onboarding wizards.](https://apidocs.hibob.com/reference/get_onboarding-wizards.md): Wizard info includes Wizard ID, name and description.
    Supported user types: Service. - [Onboarding](https://apidocs.hibob.com/reference/onboarding.md): The Onboarding API provides access to the details of your onboarding wizards. - [Read avatar for an employee ID.](https://apidocs.hibob.com/reference/get_avatars-employeeid.md): Returns the avatar image URL of the employee. - [Read avatar for an employee email](https://apidocs.hibob.com/reference/get_avatars.md): Returns the avatar image URL of the employee. - [Read the public profile section of all active employees.](https://apidocs.hibob.com/reference/get_profiles.md):

    Returns a predefined list of fields for all active employees the service user can access. Refer to the '200' response for the response schema.

    Ensure the service user has the necessary permissions to access all the users and fields you want to retrieve, including the vasic default fields permissions.

    Explore the People API main reference page for information about rate limits, permissions, troubleshooting and more.

    - [People](https://apidocs.hibob.com/reference/people.md): The People API provides access to the details of your company employees. - [Invite an employee with a welcome wizard ID.](https://apidocs.hibob.com/reference/post_employees-employeeid-invitations.md):

    Explore the People API main reference page for information about rate limits, permissions, troubleshooting and more.

    - [Set or update an employee's start date.](https://apidocs.hibob.com/reference/post_employees-employeeid-start-date.md):

    Explore the People API main reference page for information about rate limits, permissions, troubleshooting and more.

    - [Terminate company employee.](https://apidocs.hibob.com/reference/post_employees-identifier-terminate.md): This changes the employee’s status to Terminated according to specified termination date.

    Explore the People API main reference page for information about rate limits, permissions, troubleshooting and more.

    - [Revoke access to Bob for an employee.](https://apidocs.hibob.com/reference/post_employees-identifier-uninvite.md):

    Explore the People API main reference page for information about rate limits, permissions, troubleshooting and more.

    - [Read company employee fields by employee ID.](https://apidocs.hibob.com/reference/post_people-identifier.md): This endpoint allows you to retrieve employee data based on specified criteria.
    Please note that this endpoint requires body parameters, which is why it utilizes a POST request for a read operation.

    **Before using this endpoint:**

    1. **Explore the People API main reference page** for information about rate limits, permissions, troubleshooting and more.
    2. **Note that only employee fields are supported**. Table entries cannot be retrieved via this endpoint. Use Employee Tables endpoints for this.
    3. **Default fields**. If no specific fields are requested, a **default set** of fields will be returned, as listed in the 200 response, based on the service user permissions. If you want to retrieve other fields, you will need to specify their field id in the body parameters.
    4. **Custom fields**. To retrieve custom fields you need to specify their field id in the body parameters and ensure you have the approriate permissions to the category.
    5. **Position** fields cannot be retrieved using this endpoint. To pull 'Positions', use the Workforce Planning endpoints.

    **Testing notes**:

    1. Use the testing widget's **Try It!** option to test this endpoint.
    2. Use the **Examples > Request Example** option to see how to initiate body parameters.
    3. Explore the response payload using the **Example** in the Response on the right, to understand the structure. You can see the response for the human-readable format and for the machine-format (backend IDs).

    - [Search for employees](https://apidocs.hibob.com/reference/post_people-search.md): This endpoint allows you to retrieve employee data based on specified criteria.
    Please note that this endpoint requires body parameters, which is why it utilizes a POST request for a read operation.

    **Before using this endpoint:**

    1. **Explore the People API main reference page** for information about rate limits, permissions, troubleshooting and more.
    2. **Note that only employee fields are supported**. Table entries cannot be retrieved via this endpoint. Use Employee Tables endpoints for this.
    3. **Default fields**. If no specific fields are requested, a **default set** of fields will be returned, as listed in the 200 response, based on the service user permissions. If you want to retrieve other fields, you will need to specify their field id in the body parameters.
    4. **Custom fields**. To retrieve custom fields you need to specify their field id in the body parameters and ensure you have the approriate permissions to the category.
    5. **Position** fields cannot be retrieved using this endpoint. To pull 'Positions', use the Workforce Planning endpoints.

    **Testing notes**:

    1. Use the testing widget's **Try It!** option to test this endpoint.
    2. Use the **Examples > Request Example** option to see how to initiate body parameters.
    3. Explore the response payload using the **Example** in the Response on the right, to understand the structure. You can see the response for the human-readable format and for the machine-format (backend IDs).

    - [Create company employee.](https://apidocs.hibob.com/reference/post_people.md):
    This creates a new employee record in Bob. You can include only the fields listed in the [Fields Metadata API](https://apidocs.hibob.com/reference/get_company-people-fields).

    Note - [Upload employee's avatar by image url](https://apidocs.hibob.com/reference/put_avatars-employeeid.md): Upload an employee's Avatar by providing a URL to the image to upload.
    - [Update an employee's email address.](https://apidocs.hibob.com/reference/put_people-id-email.md): Change an employee's email address. If you cannot change the self email an invitation will be sent to the new address to verify the email if the employee is invited/active.
    - [Update company employee.](https://apidocs.hibob.com/reference/put_people-identifier.md): This endpoint allows you to update specific fields in an employee's record in Bob.

    **Important**: Although this is a PUT method, it behaves like a PATCH request—you only need to send the fields you want to update, and any other fields will remain unchanged.

    **Before using this endpoint**, read the instructions on how to update employee data. You can find them here: Update Employee data.

    **Notes**:
    1. Only employee **fields** are supported; table updates are not allowed via this endpoint.
    2. **Position** fields cannot be updated using this endpoint.
    - [Get all job family fields](https://apidocs.hibob.com/reference/get_job-catalog-job-families-metadata.md): Returns a list of all fields of object type job family.


    **Required permissions**
    The service user making the call must have the required permissions: see Permissions required.
    - [Get all job family group fields](https://apidocs.hibob.com/reference/get_job-catalog-job-family-groups-metadata.md): Returns a list of all fields of object type job family group.


    **Required permissions**
    The service user making the call must have the required permissions: see Permissions required.
    - [Get all job profiles fields](https://apidocs.hibob.com/reference/get_job-catalog-job-profiles-metadata.md): Returns a list of all fields of object type job profile.


    **Required permissions**
    The service user making the call must have the required permissions: see Permissions required.
    - [Get all job role fields](https://apidocs.hibob.com/reference/get_job-catalog-job-roles-metadata.md): Returns a list of all fields of object type job role.


    **Required permissions**
    The service user making the call must have the required permissions: see Permissions required.
    - [Job catalog settings](https://apidocs.hibob.com/reference/job-catalog-settings.md): Retrieve profile, roles, family and family groups attributes (metadata) - [Get all job families](https://apidocs.hibob.com/reference/get_job-catalog-job-families.md): Returns a list of all objects of type job family.


    **Required permissions**
    The service user making the call must have the required permissions: see Permissions required.

    **Pagination**
    This endpoint uses cursor-based pagination to handle large number of table entries. To learn more, see Pagination in Bob's API - [Get all job family groups](https://apidocs.hibob.com/reference/get_job-catalog-job-family-groups.md): Returns a list of all objects of type job family group.


    **Required permissions**
    The service user making the call must have the required permissions: see Permissions required.

    **Pagination**
    This endpoint uses cursor-based pagination to handle large number of table entries. To learn more, see Pagination in Bob's API - [Get all job roles](https://apidocs.hibob.com/reference/get_job-catalog-job-roles.md): Returns a list of all objects of type job role.


    **Required permissions**
    The service user making the call must have the required permissions: see Permissions required.

    **Pagination**
    This endpoint uses cursor-based pagination to handle large number of table entries. To learn more, see Pagination in Bob's API - [Job content library](https://apidocs.hibob.com/reference/job-content-library.md): Retrieve roles, families and family groups. - [Job profiles](https://apidocs.hibob.com/reference/job-profiles.md): Access to Job profiles in your company. - [Read company job profiles](https://apidocs.hibob.com/reference/post_job-catalog-job-profiles-search.md): This endpoint returns a list of company job profiles filtered by the specified attributes. Note that this endpoint requires body parameters, which is why it is implemented as a POST request.

    To successfully use this endpoint, a filter is mandatory. Ensure you use the filter provided in the **Example > Request example** option; otherwise, the call will fail.

    **Required permissions**
    The service user making the call must have the required permissions: see Permissions required.

    **Pagination**
    This endpoint uses cursor-based pagination to handle large number of table entries. To learn more, see Pagination in Bob's API - [Download a report by the report name.](https://apidocs.hibob.com/reference/get_company-reports-download-reportname.md): Downloads the report that was generated with the Get the report download URL for polling endpoint.

    To download the report:
    1. Use the [Get the report download URL for polling](https://apidocs.hibob.com/reference/get_company-reports-reportid-download-async) endpoint to obtain the report URL.
    2. Copy only the name of the report (after the /download/) from the URL returned in the response header, and use it as the `reportName` for download.

    For example: `https://app.hibob.com/v1/company/reports/download/2022-06-17T11_22_14.798810-test.JsonFormat`
    3. If you receive 204 error response, this means the reports is not ready yet. In this case you should try again.

    Permissions required:
    The service user that you use for this call should have the required permissions. To learn more, see [Reports permissions](https://apidocs.hibob.com/reference/reports). - [Get the report download URL for polling](https://apidocs.hibob.com/reference/get_company-reports-reportid-download-async.md): This endpoint asynchronously generates a report, based on the specified format. If successful it returns the status `Accepted` and sets the URL of the newly generated report in the response header under a header called `Location`.
    You can then obtain the report name and pass it to the next endpoint ([Download report file by URL](https://apidocs.hibob.com/reference/get_company-reports-download-reportname)):
    1. Click **Headers** at the bottom of the response to see the URL.
    2. Copy only the name of the report (after the /download/ part) and paste to the `reportName` for download.

    Permissions required:
    The service user that you use for this call should have the required permissions. To learn more, see [Reports permissions](https://apidocs.hibob.com/reference/reports). - [Download the report by ID](https://apidocs.hibob.com/reference/get_company-reports-reportid-download.md): Returns a report data file in the specified format.
    Supported user types: Service.

    Permissions required:
    The service user that you use for this call should have the required permissions. To learn more, see [Reports permissions](https://apidocs.hibob.com/reference/reports). - [Read company reports](https://apidocs.hibob.com/reference/get_company-reports.md): Returns a list of all the company reports with their details. The data is filtered based on the access level of the service user making the call. Only viewable categories are returned.

    Permissions required:
    The service user that you use for this call should have the required permissions to access reports. To learn more, see [Reports permissions](https://apidocs.hibob.com/reference/reports). - [Reports](https://apidocs.hibob.com/reference/reports.md): The Reports API provides access to the details of your company reports. - [Start developing with the API](https://apidocs.hibob.com/reference/getting-started-with-bob-api.md): Get started with Bob's API reference guide - [Read tasks of a specific employee ](https://apidocs.hibob.com/reference/get_tasks-people-id.md) - [Read all open tasks.](https://apidocs.hibob.com/reference/get_tasks.md) - [Tasks](https://apidocs.hibob.com/reference/tasks.md): The Tasks API provides access to the details of tasks. - [Mark a task as complete](https://apidocs.hibob.com/reference/post_tasks-taskid-complete.md) - [Attendance](https://apidocs.hibob.com/reference/attendance.md): The Attendance API provides a way 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.

    **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. - [Employee events (v1)](https://apidocs.hibob.com/reference/employee-changes-events.md): The following events can be used to create Employee data updates Webhooks. - [Task events (v1)](https://apidocs.hibob.com/reference/employee-task-events.md): Receive notifications about triggered task lists and tasks status updates. - [eSign events (v1)](https://apidocs.hibob.com/reference/esign-document-signing-event.md) - [Webhooks v1 (Legacy)](https://apidocs.hibob.com/reference/webhook-events-v1.md) - [Time off events (v1)](https://apidocs.hibob.com/reference/time-off-webhook-events.md): The following events can be used to create Time off request Webhooks. - [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. - [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**.
    ## Pages - [API Changes & Deprecations](https://apidocs.hibob.com/api-changes-deprecations.md) ## Changelog - [Workforce planning API: Prorated cost](https://apidocs.hibob.com/changelog/workforce-planning-api-prorated-cost.md) - [Time off API: Get Policy Type - final removal of property](https://apidocs.hibob.com/changelog/time-off-api-get-policy-final-removal-of-property.md) - [🎧 Just added: Our first AI audio summary](https://apidocs.hibob.com/changelog/just-added-our-first-ai-summary-in-audio-format.md) - [Final deprecation notice: `GET /people` endpoints and API Tokens](https://apidocs.hibob.com/changelog/final-deprecation-notice-get-people-and-api-tokens.md) - [New: AI-friendly tools in the Developer Hub](https://apidocs.hibob.com/changelog/new-ai-friendly-tools-in-the-developer-hub.md)