# Developer Docs Documentation > The Developer Docs is where you'll find comprehensive guides and documentation to help you start working with Bob as quickly as possible. Fetch the complete documentation index at: https://apidocs.hibob.com/llms.txt. Use this file to discover all available pages before exploring further. Append .md to any documentation page URL to get its markdown version. ## API Reference: Start developing - [Start developing index](https://apidocs.hibob.com/reference/start-developing/llms.txt): full category index - [Start developing with the API](https://apidocs.hibob.com/reference/getting-started-with-bob-api.md): Get started with Bob's API reference guide ## API Reference: Core Concepts - [Core Concepts index](https://apidocs.hibob.com/reference/core-concepts/llms.txt): full category index - [Authorization](https://apidocs.hibob.com/reference/authorization.md): How to build the authorization header when sending HTTP calls to Bob. - [Permissions](https://apidocs.hibob.com/reference/permissions.md): Learn about setting service user permissions to access the data in Bob - [Testing](https://apidocs.hibob.com/reference/testing.md): Learn how to test endpoints using your own data - [Rate limiting](https://apidocs.hibob.com/reference/rate-limiting.md): Learn how we limit access to endpoints and to our server - [Pagination](https://apidocs.hibob.com/reference/pagination-1.md): Bob offers cursor-based pagination for some of our API’s collection endpoints. - [Object-based endpoints](https://apidocs.hibob.com/reference/object-based-endpoints.md): Learn about the new object-based endpoints in our public API - [Error handling](https://apidocs.hibob.com/reference/error-handling.md): Learn how Bob's public APIs handle errors ## API Reference: Core concepts for partners - [Core concepts for partners index](https://apidocs.hibob.com/reference/core-concepts-for-partners/llms.txt): full category index - [OAuth 2.0](https://apidocs.hibob.com/reference/oauth-20.md): Learn how partners can use HiBob's OAuth Integration - [Scopes mapping to endpoints](https://apidocs.hibob.com/reference/scopes-mapping-to-endpoints.md): Learn how to work with scopes when integrating with ob ## API Reference: Webhooks - [Webhooks index](https://apidocs.hibob.com/reference/webhooks/llms.txt): full category index - [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. - [Sample API calls from webhook](https://apidocs.hibob.com/reference/api-calls-for-webhook-events.md): API calls examples to retrieve the data relevant to webhook events - [[ Legacy] Webhooks v1](https://apidocs.hibob.com/reference/webhook-events-v1.md) - [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. - [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. - [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) ## API Reference: Employee data API - [Employee data API index](https://apidocs.hibob.com/reference/employee-data-api/llms.txt): full category index - [People](https://apidocs.hibob.com/reference/people.md): The People API provides access to the details of your company employees. - [Search for employees](https://apidocs.hibob.com/reference/post_people-search.md): Search employee fields for many employees in one call.

See Critical behaviors below on this page for field IDs, filters, showInactive, permissions, no pagination, large-company batching, and integration limits. Full contract: People read API contract.

Testing notes:

  1. Use Try It! and Examples > Request Example (default: active employees only; other examples cover terminated employees and batched reads by ID).
  2. Explore the response payload using the Example in the Response panel.
- [Read company employee fields by employee ID.](https://apidocs.hibob.com/reference/post_people-identifier.md): Single-employee read endpoint (not bulk search): returns field data for one employee identified by backend ID or email in the path in a single response. No pagination. For many employees in one call, use Search for employees. See Pagination and result scope. This endpoint uses POST (not GET) because the request body selects fields.

Before using this endpoint — see the People read API contract and People API (rate limits, permissions table, troubleshooting):

Testing notes:

  1. Use the testing widget's Try It! option to test this endpoint.
  2. Use Examples > Request Example to see body parameters.
  3. Explore the response payload using the Example in the Response panel (human-readable and machine-format).
- [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.
  3. Recently updated employee data may take a few seconds to become available when fetching data. If you read immediately after an update, the response may still show the previous value or null. Wait up to 20 seconds before a follow-up read. See Read-after-update consistency.
- [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.

- [Create company employee.](https://apidocs.hibob.com/reference/post_people.md):
This endpoint allows you to create a new employee in the system.
The request body must include the minimum required fields: `email`, `firstName`, `surname`, and the `work` object with `site` and `startDate`.
While not all fields are mandatory, we recommend populating as many fields as possible to ensure complete employee records from the start.
Specifically, it's recommended to include `work.department` and `work.title`.
You can include **any additional fields** from the [Fields Metadata API](https://apidocs.hibob.com/reference/get_company-people-fields) to enrich the employee's profile during creation. - [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.

- [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.

- [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.

- [Read avatar for an employee email](https://apidocs.hibob.com/reference/get_avatars.md): Returns the avatar image URL of the employee. - [Read avatar for an employee ID.](https://apidocs.hibob.com/reference/get_avatars-employeeid.md): Returns the avatar image URL of the employee. - [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.
- [Onboarding](https://apidocs.hibob.com/reference/onboarding.md): The Onboarding API provides access to the details of your onboarding wizards. - [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. - [Metadata](https://apidocs.hibob.com/reference/metadata.md): The Matadata API provides access to the details of your company resources. - [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 . - [Create a new field.](https://apidocs.hibob.com/reference/post_company-people-fields.md) - [Update an existing field](https://apidocs.hibob.com/reference/put_company-people-fields-fieldid.md) - [Delete an existing field.](https://apidocs.hibob.com/reference/delete_company-people-fields-fieldid.md) - [Get all company lists](https://apidocs.hibob.com/reference/get_company-named-lists.md) - [Get a specific company list by name.](https://apidocs.hibob.com/reference/get_company-named-lists-listname.md) - [Add a new item to an existing list.](https://apidocs.hibob.com/reference/post_company-named-lists-listname.md) - [Update an existing item from a list.](https://apidocs.hibob.com/reference/put_company-named-lists-listname-itemid.md) - [Delete an item from an existing list.](https://apidocs.hibob.com/reference/delete_company-named-lists-listname-itemid.md) - [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. - [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 all the work table entries**: People's Data > People's fields > Work > View history, and View on the category or required fields.
**For the current effective work entry only**: People's Data > People's fields > Work > View.
**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 all the lifecycle table entries**: People's Data > People's fields > Lifecycle (Table) > View history, and View on the table or required columns.
**For the current effective lifecycle entry only**: People's Data > People's fields > Lifecycle (Table) > View.
**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 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 all the employment table entries: People's Data > People's fields > Employment > View history, and View on the category or required fields.

  • For the current effective employment entry only: People's Data > People's fields > Employment > View.
  • 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 all the salary table entries**: People's Data > People's fields > Salary (Table) > View history, and View on the table or required columns.
    **For the current effective salary entry only**: People's Data > People's fields > Salary (Table) > View.
    **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 dependents for a list of employees](https://apidocs.hibob.com/reference/get_bulk-people-dependents.md): Returns dependent entries for all employees or a specific list of employees. In the Bob UI this table may appear as Children or Dependents, depending on your company configuration.

    You can fetch employee IDs using the People search endpoint.

    **Required permissions**
    People's Data > People's fields > Home > View (or Edit), or the equivalent Children/Dependents table permissions under People's fields.
    **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 equity grants for a list of employees](https://apidocs.hibob.com/reference/get_bulk-people-equities.md): Returns equity table entries for all employees or a specific list of employees. Each entry in values uses the same schema as List the employee's equity grants.

    You can fetch employee IDs using the People search endpoint.

    **Required permissions**
    People's Data > People's fields > Payroll / Equity — View (or the equivalent table-level permission under People's fields).
    **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 numbers of table entries. To learn more, see Pagination in Bob's API - [List right to work entries for a list of employees](https://apidocs.hibob.com/reference/get_bulk-people-right-to-work.md): Returns right to work entries for all employees or a specific list of employees.

    You can fetch employee IDs using the People search endpoint.

    **Required permissions**
    People's Data > People's fields > Right to Work > View (or the equivalent Right to Work table permissions under People's fields).
    **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 variable pay entries for a list of employees](https://apidocs.hibob.com/reference/get_bulk-people-variable.md): Returns variable pay table entries for all employees or a specific list of employees. Variable pay is a multi-current history table: an employee may have multiple variable types concurrently (for example Bonus and Commission), each with its own effective-date timeline. Responses include timeline fields such as `effectiveDate`, `endEffectiveDate`, and `isCurrent`.

    You can fetch employee IDs using the People search endpoint.

    **Required permissions**
    People's Data > People's fields > Variable Pay (Table) > View history (and View on the table or required columns), or View for current-effective rows only.
    **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 entitlement entries for a list of employees](https://apidocs.hibob.com/reference/get_bulk-people-entitlement.md): Returns entitlement table entries for all employees or a specific list of employees. Entitlement is a multi-current history table: an employee may have multiple entitlement types concurrently (for example Lunch vouchers and Company Car), each with its own effective-date timeline. Responses include timeline fields such as `effectiveDate`, `endEffectiveDate`, and `isCurrent`.

    There is no per-employee GET for this table — use this bulk endpoint with a single `employeeIds` value when you need one employee.

    You can fetch employee IDs using the People search endpoint.

    **Required permissions**
    People's Data > People's fields > Entitlement (Table) > View history (and View on the table or required columns), or View for current-effective rows only.
    **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 deduction entries for a list of employees](https://apidocs.hibob.com/reference/get_bulk-people-deduction.md): Returns deduction table entries for all employees or a specific list of employees. Deduction is a multi-current history table: an employee may have multiple deduction types concurrently (for example Childcare vouchers and Health insurance), each with its own effective-date timeline. Responses include timeline fields such as `effectiveDate`, `endEffectiveDate`, and `isCurrent`.

    There is no per-employee GET for this table — use this bulk endpoint with a single `employeeIds` value when you need one employee.

    You can fetch employee IDs using the People search endpoint.

    **Required permissions**
    People's Data > People's fields > Deduction (Table) > View history (and View on the table or required columns), or View for current-effective rows only.
    **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 - [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
    **For all the actual payments table entries**: People's Data > People's fields > Actual Payments (Table) > View history, and View on the table or required columns.
    **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.

    **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. **To test more than a single filter**, copy the example to an external API testing app like Postman for better filtering options.
    4. Response Example: View the response payload using the **Response > Response example** option in the response on the right. - [List employee's work history](https://apidocs.hibob.com/reference/get_people-id-work.md): Returns a list of historical work entries from the work table for an employee.

    **Required permissions**
    In order to access the work history, the service user making the call must have the following permissions:
    **For all the work table entries**: People's Data > People's fields > Work > View history, and View on the category or required fields.
    **For the current effective work entry only**: People's Data > People's fields > Work > View.
    **For the employee**: People's Data > Access data for > Make sure the employee is in the list.

    - [Create a new work entry for a given employee.](https://apidocs.hibob.com/reference/post_people-id-work.md) - [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. - [Deletes a work entry from a given employee's work history.](https://apidocs.hibob.com/reference/delete_people-id-work-entry-id.md) - [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

  • For all the employment table entries: People's Data > People's fields > Employment > View history, and View on the category or required fields.

  • For the current effective employment entry only: People's Data > People's fields > Employment > View.
  • 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.

    • - [Creates a new employment entry for a given employee.](https://apidocs.hibob.com/reference/post_people-id-employment.md) - [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).

    - [Deletes an employment entry from a given employee's employment history.](https://apidocs.hibob.com/reference/delete_people-id-employment-entry-id.md) - [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 all the lifecycle table entries**: People's Data > People's fields > Lifecycle (Table) > View history, and View on the table or required columns.
    **For the current effective lifecycle entry only**: People's Data > People's fields > Lifecycle (Table) > View.
    **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 all the salary table entries**: People's Data > People's fields > Salary (Table) > View history, and View on the table or required columns.
    **For the current effective salary entry only**: People's Data > People's fields > Salary (Table) > View.
    **For the employee**: People's Data > Access data for > Make sure the employee is in the list. - [Creates a new salary entry for a given employee.](https://apidocs.hibob.com/reference/post_people-id-salaries.md) - [Deletes a salary entry from the employee's list.](https://apidocs.hibob.com/reference/delete_people-id-salaries-entry-id.md) - [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 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. - [Creates a new equity grant for a given employee.](https://apidocs.hibob.com/reference/post_people-id-equities.md) - [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).

    - [Deletes an equity grant for an employee.](https://apidocs.hibob.com/reference/delete_people-id-equities-entry-id.md) - [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. For multi-employee sync jobs, prefer List variable pay entries for a list of employees. - [Creates a new variable payment for a given employee.](https://apidocs.hibob.com/reference/post_people-id-variable.md): Creates a new variable pay entry for the employee. On success, returns the new entry id. For multi-employee reads, use List variable pay entries for a list of employees.

    **Required permissions**: People's Data > People's fields > Variable Pay (Table) > Edit. - [Update a variable payment for an employee](https://apidocs.hibob.com/reference/put_people-id-variable-entry-id.md): Updates an existing variable pay entry for the given employee. Send the full row (not a partial patch). Returns no content on success.

    **Required permissions**: People's Data > People's fields > Variable Pay (Table) > Edit. - [Deletes a variable payment record for an employee.](https://apidocs.hibob.com/reference/delete_people-id-variable-entry-id.md): Deletes a variable pay entry for the given employee. Returns no content on success.

    **Required permissions**: People's Data > People's fields > Variable Pay (Table) > Edit. - [Create an entitlement entry for an employee](https://apidocs.hibob.com/reference/post_people-id-entitlement.md): Creates a new entitlement table entry for the employee. On success, returns the new entry id. Creating or updating entries may also sync current entitlement amounts onto derived employee fields such as `payroll.entitlement..amount` (employee fields you can fetch with the People search endpoint).

    To read entitlement rows, use List entitlement entries for a list of employees (there is no per-employee GET).

    **Required permissions**: People's Data > People's fields > Entitlement (Table) > Edit. - [Update an entitlement entry for an employee](https://apidocs.hibob.com/reference/put_people-id-entitlement-entry-id.md): Updates an existing entitlement entry for the given employee. Send the full row (not a partial patch). Returns no content on success.

    **Required permissions**: People's Data > People's fields > Entitlement (Table) > Edit. - [Delete an entitlement entry for an employee](https://apidocs.hibob.com/reference/delete_people-id-entitlement-entry-id.md): Deletes an entitlement entry for the given employee. Returns no content on success.

    **Required permissions**: People's Data > People's fields > Entitlement (Table) > Edit. - [Create a deduction entry for an employee](https://apidocs.hibob.com/reference/post_people-id-deduction.md): Creates a new deduction table entry for the employee. On success, returns the new entry id. The combination of `effectiveDate` and `deduction` must be unique per employee; duplicate pairs are rejected. Creating or updating entries may also sync current deduction amounts onto derived employee fields such as `payroll.deduction..amount` (employee fields you can fetch with the People search endpoint).

    To read deduction rows, use List deduction entries for a list of employees (there is no per-employee GET).

    **Required permissions**: People's Data > People's fields > Deduction (Table) > Edit. - [Update a deduction entry for an employee](https://apidocs.hibob.com/reference/put_people-id-deduction-entry-id.md): Updates an existing deduction entry for the given employee. Send the full row (not a partial patch). Returns no content on success.

    **Required permissions**: People's Data > People's fields > Deduction (Table) > Edit. - [Delete a deduction entry for an employee](https://apidocs.hibob.com/reference/delete_people-id-deduction-entry-id.md): Deletes a deduction entry for the given employee. Returns no content on success.

    **Required permissions**: People's Data > People's fields > Deduction (Table) > Edit. - [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. - [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. - [Deletes any training records for an employee.](https://apidocs.hibob.com/reference/delete_people-id-training-entry-id.md) - [Create a dependent entry for an employee](https://apidocs.hibob.com/reference/post_people-id-dependents.md): Creates a new dependent entry for the employee. In the Bob UI this table may appear as Children or Dependents, depending on your company configuration. On success, returns the new entry id. Creating or deleting dependents also updates the employee's `home.numberOfKids` field (an employee field you can fetch with the People search endpoint).

    **Required permissions**: People's Data > People's fields > Home > Edit (or Children/Dependents table Edit). - [Update a dependent entry for an employee](https://apidocs.hibob.com/reference/put_people-id-dependents-entry-id.md): Updates an existing dependent entry for the given employee. In the Bob UI this table may appear as Children or Dependents, depending on your company configuration. Returns no content on success.

    **Required permissions**: People's Data > People's fields > Home > Edit (or Children/Dependents table Edit). - [Delete a dependent entry for an employee](https://apidocs.hibob.com/reference/delete_people-id-dependents-entry-id.md): Deletes a dependent entry for the given employee. In the Bob UI this table may appear as Children or Dependents, depending on your company configuration. Returns no content on success. Also updates the employee's `home.numberOfKids` field (an employee field you can fetch with the People search endpoint).

    **Required permissions**: People's Data > People's fields > Home > Edit (or Children/Dependents table Edit). - [Create a right to work entry for an employee](https://apidocs.hibob.com/reference/post_people-id-right-to-work.md): Creates a new right to work entry for the employee. On success, returns the new entry id. Creating, updating, or deleting entries also updates the employee's `financial.rightToWorkExpiryDate` field (an employee field you can fetch with the People search endpoint).

    **Required permissions**: People's Data > People's fields > Right to Work > Edit. - [Update a right to work entry for an employee](https://apidocs.hibob.com/reference/put_people-id-right-to-work-entry-id.md): Updates an existing right to work entry for the given employee. Returns no content on success. Also updates the employee's `financial.rightToWorkExpiryDate` field.

    **Required permissions**: People's Data > People's fields > Right to Work > Edit. - [Delete a right to work entry for an employee](https://apidocs.hibob.com/reference/delete_people-id-right-to-work-entry-id.md): Deletes a right to work entry for the given employee. Returns no content on success. Also updates the employee's `financial.rightToWorkExpiryDate` field (an employee field you can fetch with the People search endpoint).

    **Required permissions**: People's Data > People's fields > Right to Work > Edit. - [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.

    Important:
    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).

    If you are using a list of Bank Accounts:
    Use this endpoint will fetch the list of bank accounts.
    Use the Read metadata for specific custom table endpoint and provide the table name: `bankAccounts` to fetch the table's metadata.

    If you are using only a single Bank Account:
    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. - [Create a new bank account entry for a given employee.](https://apidocs.hibob.com/reference/post_people-id-bank-accounts.md) - [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.

    - [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) - [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. - [Read metadata of custom tables defined](https://apidocs.hibob.com/reference/get_people-custom-tables-metadata.md) - [Read metadata for specific custom table](https://apidocs.hibob.com/reference/get_people-custom-tables-metadata-custom-table-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) - [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. Columns that are defined as **Mandatory** (from the custom column's settings) must be provided.
    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): Provide an array of columns and their values.
    **Important**: Although this is a PUT method, it behaves like a PATCH request, meaning you only need to send the fields you want to update, and any other fields will remain unchanged.
    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. - [Delete custom table entry](https://apidocs.hibob.com/reference/delete_people-custom-tables-employee-id-custom-table-id-entry-id.md) - [Employee data Webhooks](https://apidocs.hibob.com/reference/employee-data-webhooks.md): Receive notificaions about employee updates - [Employee created](https://apidocs.hibob.com/reference/post_webhook_employee-created.md): Triggered when an employee is created. In the right panel, open **Examples** and select **Payload Example** to see a real payload. - [Employee updated](https://apidocs.hibob.com/reference/post_webhook_employee-updated.md): Triggered when an employee's field is updated. The payload includes only the fields that were explicitly changed. Calculated fields affected by an update (e.g., age when birthDate changes) are not included. This event is also sent when a table entry create or update causes employee-level fields to change; the payload then contains the affected field IDs in fieldUpdates. Bank accounts and custom tables do not trigger this event when their entries change. In the right panel, open **Examples** and select **Payload Example** to see a real payload. - [Employee deleted](https://apidocs.hibob.com/reference/post_webhook_employee-deleted.md): Triggered when an employee is deleted. The payload includes the employee email so you can retain a reference to the deleted employee after their record is no longer accessible. In the right panel, open **Examples** and select **Payload Example** to see a real payload. - [Employee joined](https://apidocs.hibob.com/reference/post_webhook_employee-joined.md): Triggered when an employee is granted access, once the corresponding lifecycle entry becomes effective. Lifecycle events are triggered automatically at midnight on the effective date of the lifecycle table entry (according to the site's timezone). In the right panel, open **Examples** and select **Payload Example** to see a real payload. - [Employee terminated](https://apidocs.hibob.com/reference/post_webhook_employee-left.md): Triggered when an employee is set as terminated or on Garden leave (whichever occurs first), once the corresponding lifecycle entry becomes effective. Lifecycle events are triggered automatically at midnight on the effective date of the lifecycle table entry (according to the site's timezone). In the right panel, open **Examples** and select **Payload Example** to see a real payload. - [Employee activated](https://apidocs.hibob.com/reference/post_webhook_employee-activated.md): Triggered when an employee's access is enabled, once the corresponding lifecycle entry becomes effective. In the right panel, open **Examples** and select **Payload Example** to see a real payload. - [Employee inactivated](https://apidocs.hibob.com/reference/post_webhook_employee-inactivated.md): Triggered when an employee is set to be on leave or terminated, once the corresponding lifecycle entry becomes effective. This event is not triggered if **Remain active** is selected when putting the employee on leave. In the right panel, open **Examples** and select **Payload Example** to see a real payload. - [Employee on temporary leave](https://apidocs.hibob.com/reference/post_webhook_employee-temporary-leave.md): Triggered when an employee is set to be on temporary leave, once the corresponding lifecycle entry becomes effective. This event is not triggered if **Remain active** is selected when putting the employee on leave. In the right panel, open **Examples** and select **Payload Example** to see a real payload. - [Table entry created](https://apidocs.hibob.com/reference/post_webhook_table-entry-created.md): Triggered when an entry is added to an employee's table (including out-of-the-box and custom tables). Does not apply to Training, Equity, Positions, or Jobs tables. To identify the row/entry when fetching using the API, use the property that appears in the payload for that table type: - **id** — Included only for non-historical tables (e.g. custom tables, bank accounts). Identifies the entry row. Omitted for historical tables. - **effectiveDate** — Included only for historical tables. Identifies the entry row for that table type. Omitted for non-historical tables. Each event includes exactly one of `effectiveDate` or `id` inside `data`, depending on whether the table is historical. To learn more about table types, see Employee data modeling. When a table entry is created or updated, it may also update employee-level fields (e.g. derived or linked). In that case you will also receive an employee.updated event with the list of changed field IDs in fieldUpdates. Bank accounts and custom tables do not trigger this additional employee.updated event. In the right panel, open **Examples** and select **Payload Example** to see a real payload. - [Table entry updated](https://apidocs.hibob.com/reference/post_webhook_table-entry-updated.md): Triggered when an entry is updated in an employee's table (including out-of-the-box and custom tables). Does not apply to Training, Equity, Positions, or Jobs tables. To identify the row/entry when fetching using the API, use the property that appears in the payload for that table type: - **id** — Included only for non-historical tables (e.g. custom tables, bank accounts). Identifies the entry row. Omitted for historical tables. - **effectiveDate** — Included only for historical tables. Identifies the entry row for that table type. Omitted for non-historical tables. Each event includes exactly one of `effectiveDate` or `id` inside `data`, depending on whether the table is historical. To learn more about table types, see Employee data modeling. When a table entry is created or updated, it may also update employee-level fields (e.g. derived or linked). In that case you will also receive an employee.updated event with the list of changed field IDs in fieldUpdates. Bank accounts and custom tables do not trigger this additional employee.updated event. In the right panel, open **Examples** and select **Payload Example** to see a real payload. ## API Reference: Time Off API - [Time Off API index](https://apidocs.hibob.com/reference/time-off-api/llms.txt): full category index - [Time off requests](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. - [Get the details of an existing time off request.](https://apidocs.hibob.com/reference/get_timeoff-employees-id-requests-requestid.md): Retrieve the detailed info about an existing time off request.

    Possible time off request types: Each request type is represented by a separate schema with the relevant fields.

    Daily durations and cost:This endpoint returns a full daily duration and cost breakdown for all request types when includeDailyDurations=true is provided.

    Permissions required: Please refer to the main Time off API Required Permissions page.

    - [Cancel an existing time off request](https://apidocs.hibob.com/reference/delete_timeoff-employees-id-requests-requestid.md): Cancels an existing time off request.

    **Permissions required**: Please refer to the main Time off API Required Permissions page. - [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:**

    Durations and cost:

    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: Each request type is represented by a separate schema with the relevant fields.

    Durations and cost:

    Notes:

    - [Read a list of who's out of the office today or on the specified date.](https://apidocs.hibob.com/reference/get_timeoff-outtoday.md): Returns the list of people that have a time off request today or on the specified date, only for the users the Service User can access.

    Possible time off request types (requestRangeType): Each request type is represented by a separate schema with the relevant fields.

    Durations and cost:

    Notes:

    - [Time off balance](https://apidocs.hibob.com/reference/time-off-balance.md) - [Get the balance for a given employee](https://apidocs.hibob.com/reference/get_timeoff-employees-id-balance.md): Retrieve the balance for a given employee, for a given policy type, as of a given date.

    **Permissions required**: Please refer to the main Time off API Required Permissions page. - [Create a balance adjustment.](https://apidocs.hibob.com/reference/post_timeoff-employees-id-adjustments.md): Create a balance adjustment for a given employee for a given effective date.

    **Permissions required**: Please refer to the main Time off API Required Permissions page. - [Time off policies](https://apidocs.hibob.com/reference/time-off-policies.md) - [Get Policy type reason codes](https://apidocs.hibob.com/reference/get_timeoff-policy-types-policytype-reason-codes.md): Get list of reason codes for a given policy type.

    **Permissions required**: Please refer to the main Time off API Required Permissions page. - [Add a list of reason codes for a given policy type.](https://apidocs.hibob.com/reference/post_timeoff-policy-types-policytype-reason-codes.md): Add a list of reason codes for a given policy type.
    Supported user types: Service.
    **Permissions required**: Please refer to the main Time off API Required Permissions page. - [Get Policy type details](https://apidocs.hibob.com/reference/get_timeoff-policy-types-policytype.md): Get details about a given policy type.

    **Permissions required**: Please refer to the main Time off API Required Permissions page.

    - [Get all policy types names.](https://apidocs.hibob.com/reference/get_timeoff-policy-types.md): Get a list of all policy type names.

    **Permissions required**: Please refer to the main Time off API Required Permissions page. - [Get Policy details.](https://apidocs.hibob.com/reference/get_timeoff-policies.md): Get details about a given policy.

    **Permissions required**: Please refer to the main Time off API Required Permissions page. - [Get a list of policy names for a given policy type.](https://apidocs.hibob.com/reference/get_timeoff-policies-names.md): Get a list of policy names for the user's defined policy type.

    **Permissions required**: Please refer to the main Time off API Required Permissions page. - [Calendar events](https://apidocs.hibob.com/reference/calendar-events.md) - [Search calendar events](https://apidocs.hibob.com/reference/post_timeoff-calendars-events-search.md): Read company-wide holidays and closures for a date range. Use with Search employee calendars to resolve which calendar applies to each employee before fetching events. - [Search Employee Calendars](https://apidocs.hibob.com/reference/post_timeoff-calendars-employees-search.md): Resolves which holiday calendar applies to each employee in a single bulk call. Each employee's effective calendar is computed server-side using the canonical resolution rule (matches Bob's product behaviour): 1. **Employment override** — if `payroll.employment.calendarId` is set on the employee's employment record **and** that calendar currently exists in the company, it is returned with `source = employment`. 2. **Site default** — otherwise, the calendar assigned to the employee's site is returned with `source = site`. 3. **None** — if neither layer supplies a calendar (no override and the site has no calendar configured, or the employee has no site), the item is returned with `source = none` and `calendarId` / `calendarName` set to `null`. **Missing employees:** Employee IDs that don't exist in the caller's company are silently dropped from `items` (the request does **not** fail). Diff the requested IDs against the returned `employeeId`s to detect unknowns. **OAuth scopes (app-user):** `timeoff.calendars:write` AND `employee_data:read`. **IAM permission:** `Settings / Calendars / Manage` (company-scoped). - [Time off Webhooks](https://apidocs.hibob.com/reference/time-off-webhooks.md): Receive notifications about Time off requests - [Time off request requested](https://apidocs.hibob.com/reference/post_webhook_timeoff-request-requested.md): Triggered when submitting a time off request. Use the **getApi** URL in the payload to retrieve the full request details. When using the getApi URL immediately after this event, the status in the response will be **approved** if the request was auto-approved, or **pending** if it is awaiting approval. In the right panel, open **Examples** and select **Payload Example** to see a real payload. - [Time off request approved](https://apidocs.hibob.com/reference/post_webhook_timeoff-request-approved.md): Triggered when approving a time off request. For auto-approved requests, two events are sent in sequence: **requested** then **approved**. In the right panel, open **Examples** and select **Payload Example** to see a real payload. - [Time off request declined](https://apidocs.hibob.com/reference/post_webhook_timeoff-request-declined.md): Triggered when declining a time off request. When using the **getApi** URL to retrieve details of a declined request, the status in the response will be **disapproved** (not "declined"). In the right panel, open **Examples** and select **Payload Example** to see a real payload. - [Time off request cancelled](https://apidocs.hibob.com/reference/post_webhook_timeoff-request-cancelled.md): Triggered when cancelling a time off request. In the right panel, open **Examples** and select **Payload Example** to see a real payload. - [Time off request deleted](https://apidocs.hibob.com/reference/post_webhook_timeoff-request-deleted.md): Triggered when deleting a time off request. In the right panel, open **Examples** and select **Payload Example** to see a real payload. - [Time off request updated](https://apidocs.hibob.com/reference/post_webhook_timeoff-request-updated.md): Triggered when updating a time off request. For date or time changes (hard-update), a new request replaces the existing one. The payload then includes **originalRequestId** (the very first request before any modifications) and **previousRequestId** (the most recently replaced request). In the right panel, open **Examples** and select **Payload Example** to see a real payload. - [Time off request created from import](https://apidocs.hibob.com/reference/post_webhook_timeoff-request-imported.md): Triggered when importing a time off request. Imported requests are always approved by default. When using the **getApi** URL immediately after this event, the status in the response will be **approved**. In the right panel, open **Examples** and select **Payload Example** to see a real payload. - [Set end date to a time off request](https://apidocs.hibob.com/reference/post_webhook_timeoff-request-set-end-date.md): Triggered when setting the end date of an open-ended time off request. In the right panel, open **Examples** and select **Payload Example** to see a real payload. ## API Reference: Attendance API - [Attendance API index](https://apidocs.hibob.com/reference/attendance-api/llms.txt): full category index - [Attendance](https://apidocs.hibob.com/reference/attendance.md): Use the API to manage attendance entries and projects in 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: