Explore Employee data API
Understand the basic concepts of employee data API in Bob
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.
| Data type | Description | Relevant | Relevant endpoints | Included in fields metadata | Can be customized by the user |
|---|---|---|---|---|---|
| Fields | Employee fields can be of any supported data types. | All OOTB fields. Historical tables' 'current' values. | People data + Fields Metadata | Yes | Yes |
| Historical fields | Fields with an 'effective date'. | 'Disability Status' | People data | Yes (current value only) | Yes |
| Calculated Fields | Fields calculated based on existing fields | For example: Full Name | People data + Fields Metadata | Yes | No |
| Lists | List items can be a value of a field. The list item can be a backend-id or the display value. | All fields | People data + Fields Metadata | No | Yes |
| Historical Tables: Single current | Single row with the 'current effective date' | Work Employment Payroll/Salary Lifecycle | People data | Yes | No |
| Historical Tables: Multi current | Multiple rows can be active based on the 'effective date' and additional keys. | Variable Pay | People data | Yes | No |
| Non-historical tables | Tables that can have duplicate rows | Custom Tables + Actual Payments, Bank Accounts, Training, Equity, Deduction, Entitlement, | People data + Fields Metadata + Employee Tables (besides Entitlement and Deduction) | Yes (besides Actual Payment) | Yes |
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.
- 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.
- 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.
| Type | Descriptions | API Endpoints |
|---|---|---|
| Fields metadata | Use this endpoint to obtain the properties of fields and historical-tables. The metadata returns all the fields that are considered the 'current' data of the employee | Get all employee fields Create a new field Update an existing field Delete an existing field. |
| Lists metadata | Use these endpoints to obtain and manage the properties of lists | Get all company lists Get a specific company list by name Add a new item to an existing list Add a new item to an existing list |
To learn more, see Metadata endpoints.
Employee data endpoints
The endpoints that provide access to the employee data include:
| Type | Description | API Endpoints |
|---|---|---|
| Get people data | Provide access to out-of-the-box fields, custom fields and current values of historical tables | Search for employees Read company employee fields by employee Read the public profile of active employees |
| Create | Use this endpoint to create an employee and get it's details back | Create company employee |
| Update | Update specific fields in an employee's record and change the employee's status | Create company employee Terminate Revoke access Invite set start date |
| Avatar | Manage avatar image files | Upload avatar Read avatar by email Read avatar by ID |
| Update the employee's work email address | Update the employee's email |
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.
| Table | Description | Actions & Limitations | API Endpoints |
|---|---|---|---|
| Lifecycle | Automatically reflects the employee’s lifecycle based on user actions in Bob, such as rehiring, placing or returning from leave, and employee termination. To learn more, check out the lifecycle status in Bob . | The changes are logged as Lifecycle entries and impact employee status. Entries cannot be added/removed by users. | Get, bulk get |
| Work | Reflects the employee’s work history. | Changes in the Lifecycle influence the Work status. | Get, bulk get, create, update, and delete |
| Employment | Captures the employee’s employment history, including job terms and working patterns. | Get, bulk get, create, update, and delete | |
| Payroll (Salary) | Captures the employee’s salary terms and history. | Get, bulk get, create, and delete | |
| Payroll (Variable Pay) | Part of Payroll tables; includes variable payments information. | Get, create, and delete | |
| Payroll (Actual Payments) | Part of Payroll tables; stores actual payments made. | Non-historical table. | Search functionality only |
| Payroll (bank accounts) | Part of Payroll tables; stores bank account details. | Non-historical table. | Get, create, update, and delete. |
| Payroll (Equity) | Part of Payroll tables. | Non-historical table. | Get, Create, update, and delete. |
| Training | Part of the Training category. | Non-historical table. | Get, create, and delete. |
The Employee Tables API reference lists the Public API endpoints.
Custom tables endpoints
The table below outlines how to access custom in Bob:
| Type | Description | API Endpoints |
|---|---|---|
| Custom tables metadata | Use these endpoints to obtain the properties of custom tables | Read metadata of custom tables defined Read metadata for specific custom table |
| Get entries | Read all the entries of a custom table | Read entries |
| Create, Update, and Delete entries | Create new custom table entry Update custom table entry Delete custom table entry |
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
Updated 3 months ago