Overview

Bob's Public APIs and Webhooks offer developers a programmatic way to access employee data efficiently. Using the REST API and Webhooks, you can communicate with Bob and leverage employee data for various business needs.

People's data fields

Bob comes with a predefined set of fields, tables, and categories that cover Bob's functionality, which is referred to as out-of-the-box (OOTB).

Any new Fields, Tables, or Categories added by users are called "custom fields," "custom tables," and "custom categories," allowing for further customization based on specific requirements.

Both OOTB and Customized data fields can be accessed via the Public API.

To learn more about customizing the employee data, see Set up People's data fields ↗.

Employee data modeling

The Employee Data API organizes data into Categories, which group related fields and tables.

Fields can be either:

• Non-historical : These are the standard data fields that hold a single value.
  • Fields can be of any of the supported data types.
  • Existing fields can be customized.
  • Users can create new custom fields.
• Historical : Fields that have an 'effective date'.
  • Historical fields can store several values, each with an effective date.
  • Based on the current date, the values with a current effective date are considered the 'current value' for this field.
  • Existing historical fields can be customized.
  • Users can create new custom fields.
• Calculated (read-only): Dynamically generated values based on other fields.
  • For example, Full Name is actually calculated based on First name + Middle name + Last name.
  • When editing the employee data from the UI, calculated fields are grayed out and cannot be updated.
  • Calculated fields can not be customized or created by users.
  • Cannot be mapped to third-party fields when setting up integrations.

Columns are fields within tables that store more multi-record data and can be either:

• Historical tables: These are out-of-the-box tables that track changes over time. Each row has an 'effective date'. Based on the current date, rows with the current effective date are considered the current data of the employee (green dot in UI) and can be retrieved when using the Employee Search API. Historical tables can be:
  • Single current: The 'effective date' is the only key. For example, the Work table.
  • Multi current: Tables with a secondary key (in addition to the 'effective date') can have a few' current' rows. For example, Variable Pay table with the key:Effective date + Variable type.
• Non-historical Tables: Do not have an 'effective date'.

📘

Note:

Calculated fields, and historical tables and columns cannot be created by the user or via the Public API.

Data access via the Public API

The following tables will help you determine which fields and tables can be accessed via the Public API and which endpoints you need to use for each.

📘

Notes:

Actual Payments: The Actual Payments table's fields are included in the fields metadata, however, this is a non-historical table that cannot be retrieved using the People data endpoints. You should use the dedicated Employee Table endpoint for this table.

1. Non-historical tables: Not all non-historical tables have an endpoint which allows to read all records. For these tables you can use the People data endpoints (e.g. Search) in order to fetch the 'current' row's data: Entitlement, Deduction, Address.
2. Workforce planning data: Some of the sections in employee's data are part of the Workforce planning module (e.g. Positions and Jobs), and should be accessed via the Workforce Planning endpoints rather than the People's data API.

Public API

Metadata endpoints

The metadata endpoints provide access to fields and list properties.

To learn more, see Metadata endpoints.

Employee data endpoints

The endpoints that provide access to the employee data include:

OOTB tables endpoints

The out-of-the-box tables in Bob are designed to support employee employment and lifecycle flows. The table below outlines which tables are accessible and highlights any limitations for specific tables.

The Employee Tables API reference lists the Public API endpoints.

Custom tables endpoints

The table below outlines how to access custom in Bob:

For the complete reference guide, see Custom Tables

Employee webhook events

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

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

Employee webhook events include:

• Creating and updating the employee profile.
• Changes to the employee's lifecycle.
• Updating employee tables.

A common use case for subscribing to Bob's webhook events is to keep external systems, like payroll or identity management tools, in sync with Bob. When an employee profile is updated, the Webhook event serves as a notification to the connected system, prompting it to call Bob's API to retrieve all relevant details. This ensures data consistency across platforms without manual input, automating updates efficiently.

To learn more, see Getting started with Webhooks.

For the reference guide, see Webhook Events.

Permissions

Categories are the primary unit for assigning permissions to access fields and tables. Each category is identified by a unique category ID, which varies between out-of-the-box categories and user-defined categories. To learn more about each category, see People's data fields glossary.

When using the Bob API, you need to authenticate with a Service User and assign the relevant permissions:

• Service Users: API service users in Bob allow you to access APIs in Bob. Multiple service users can be created, each with unique permissions, depending on the API you want to access.
• Permissions: are always assigned to categories rather than individual fields.
• Permission groups: Give you control over what information and functionalities each service user can access.

To learn more, see Categories and permissions.

Lists

Fields can be linked to a list, which holds string item values. Lists can be out-of-the-box or custom (defined by the user). All lists and their values can be retrieved using the lists metadata API.

List items backend-IDs
Each list item has a backend ID, which represents the id of the item in the list as stored in the database. The id can be a text (for out-of-the-box lists) or a number (for custom lists). In order to view the string value of the list item, you should convert it to human-readable format.

To learn more, see Fields and lists metadata.

Related resources

• How to read employee data.
• Working with employee search endpoint.
• People API reference.
• People Tables reference.
• Categories and permissions.
• Set up People's data fields.
• Rate limiting.
• Getting started with Bob API.