Read Employee data
Learn how to retrieve and process employee data using Bob’s API
The public API allows users to access employee fields, including custom fields, based on permissions granted to the service user. The employee data retrieved via the API reflects what is shown in Bob's UI, with similar permission structures organized by field category.
Before calling the API, map the fields you want to read and assign the relevant permissions to the service user accessing the API.
Note: if this is the first time you are using Bob's API, check out the API Service Users guide first.
To read employee data, follow these steps:
- Step 1: Map the fields for your query
- Step 2: Fetch fields metadata
- Step 3: Set authorization and permissions
- Step 4: Call the API or Webhook
- Step 5: Process payload
- Step 6: Fetch lists metadata
- Step 7: Read tables data (optional)
- Step 8: Set rate limits
Step 1: Map the fields for your query
Employee data in Bob consists of fields, tables, custom fields and custom tables.
First, you need to map which fields and tables you need to retrieve. You can look into Bob's employee data in the UI and decide which fields you need to access.
To learn more about fields and field types in Bob, see Set up people's data fields ↗.
Step 2: Fetch fields metadata
In this step, you need to fetch the field metadata to find out the:
- ID: you need to specify the field ID in the query you send to the search API. Fetching field metadata will return all the fields, including custom fields defined by the user. This will allow you to specify any field you need in the query.
- Category: You need the category of the field so the service user can access it. Without permissions to the field's category, the search API will not return this field in the response.
- Data type: you need to know the data type to process the field values correctly in the response payload.
To learn more about fetching the field properties, see Fields metadata.
Step 3: Set authorization and permissions
When using the Bob API you need to authenticate with a Service User.
Service users are special users in Bob which are used only for the API. The permissions assigned to a service user determine the scope of data that can be accessed.
Each endpoint may require different permissions based on the type of data you need to access. For example, accessing personal data requires different permissions than accessing an employee’s work history.
To define the permissions you need to:
- Define service users: see API Service Users.
- Set permissions based on the fields categories: see Categories and permissions
Step 4: Call the API
In this step you will build your query based on the field Ids you fetched.
Bob’s api allows you to retrieve employee data is the following ways:
- Search endpoints: Allow reading data for several employees at a time, and filtering the results based on your input. Returns a fixed set of fields by default, and you can alternatively specify which fields you want to fetch.
- Webhooks: Allow you to subscribe to events in Bob and be notified in real-time. Returns only a fixed set of fields and usually requires calling more endpoints to retrieve the complete data.
Historical data
The data you read using the Search endpoint returns the current snapshot of data about the employee. Data that is stored in historical tables will return only the "effective" entry. To read historical data, use the Employee Tables endpoints.
Call Search API
The employee /search endpoint requires the following parameters:
fields
- specify which fields you want to retrieve. If you do not provide this parameter, the call will return the default set of fields defined for this endpoint, as defined in the endpoint response. These fields include fields located in the 'root' (basic fields), 'about', 'employement', and 'work' categories.filters
- limit which employees to query. If you do not pass filters, the call will return all the employees that this service user can access.humanReadable
- determines the data format which will be returned in the fields in the response payload: machine format (default) or human readable format.showInactive
- whether the response should include inactive employees.
Moving fields to different categories:
Bob Admins can move fields to different categories. When this happens, the field will not be fetched via the "default" fetch as only the 'root' (basic fields), 'about', 'employement' and 'work' categories are fetched by default. If you can't find a field using the default query, check out Moving fields between categories.
Example: fetch all default fields for all employees (based on the service user's permissions):
POST /v1/people/search
{}
Example: fetch specific fields for a specific employee (based on the service user's permissions):
POST /v1/people/search
{
"fields": [
"/root/id", // you can use either `/` or `.` in the field id notation
"root.firstName",
"work.department"
],
"filters": \[
{
"fieldPath": "root.id",
"operator": "equals",
"values": [
"77634555747646",
]
}
}
To learn more about calling the search API, see Bob's reference guide.
Use Webhooks
Webhook events will notify you when an event occurs and will send relevant data in the event's payload. The payload returns only machine-readable format, which means you always need to find out the field types using the metadata and then convert to human-readable values.
To learn more about using Webhooks, see Getting started with Webhooks.
Step 5: Process payload
The payload that the search returns in the response includes the employee fields that were requested in the request.
Use the field metadata you fetched in step 2 in order to process the values in the fields correctly, whether the value is a number, date or an item from a list, will affects how you treat this value.
Important!
Fields containing list items need to be converted from the numeric ID to the human readable value.
Step 6: Fetch lists metadata
Fields containing list items need to be converted from the numeric ID to the human readable value. To do that you need to fetch the list items and find the item with this ID.
For example, the "department" field that contains a numeric IDs such as "209192163" should be converted to the "human readable" value "Account Receivables".
To learn more, see Converting list items to human readable format
Step 7: Read tables data (optional - for historical data)
If you need to fetch table data (e.g. Work table entries), you need to call additional API endpoints.
You can fetch table entries for a single employee or for several employees at at time (using 'bulk' endpoints).
To learn more, see Employee tables.
Step 8: Set rate limits
To ensure the stability and reliability of our platform, we have implemented rate limiting on API endpoints. These rate limits are designed to prevent misuse and overloading of the API.
When integrating with our API, it's crucial to follow these limits to us maintain optimal performance and availability for all users of the platform.
To learn more about best practices, see Rate limiting for best practices and more information.
Updated 9 days ago