Bob's People API provide powerful tools for accessing and managing employee data within your organization. These endpoints enable searching, creating, updating, and retrieving employee data.

Read this before you begin

Explore Employee Data API to learn how employee data is organized in Bob.
How to read employee data for a step-by-step guide for using the API to access employee data.

Note: This section covers employee data endpoints. To access historical data, see the Employee Tables endpoints.

Required Permissions

In Bob API, the fields are organized within categories, and the service user is granted permissions based on the category. This means all the fields in that granted category can be accessed.

Before accessing a field, ensure the service user has permission to access the relevant category, just as you would with a user within Bob.

For example, if you need the service user to pull employees' 'Personal contact' category, you would set permissions to the 'Personal contact details' section.

Permission type	Permission
Who to access	From People's data > Access rights > Edit: Select Everyone if you need to access all active employees. Select people by condition if you want specific groups or if you want also inactive employees (remove the Lifecycle status equals Employed condition. Select Specific employees for specific people only.
Read permissions	From People’s data: Select People > [category] > View selected employee's [category] section. Example: People > Personal contact details > View selected employees' Personal contact details sections
Read default fields in People search	To read basic employee data via the People search API, assign permissions to the root, about, employment, and work categories. To learn more, see Permissions for Default Employee Fields in People Search API.
Read historical records (e.g. Work table with effective date)	From People’s data: Select People > [category] > View selected employee's [category] section histories. Example: People > Personal contact details > View selected employees' Personal contact details section histories
Update permissions (e.g. terminate an employee)	From People’s data: People > [category] > Edit selected employees' [category] sections Example: People > [category] > Edit selected employees' Lifecycle sections
Create new employees	From People's data: People > Employees > Add new people to the company

To learn more, see Permissions.

Troubleshooting permission-related issues

Partial fetching/updating of Fields If you receive a '200 OK' response but notice that only some of the requested fields have been fetched or updated, this could indicate that the Service User's permissions do not cover all the requested data. The response will simply exclude any fields that the Service User does not have permission to access or modify. Important: You will not be explicitly notified that only partial permissions are available. Therefore, when testing, please ensure all expected fields are included in the response and that any permission-related issues are accounted for.
Empty response when using the Search with no 'fields' filter The 'default' search for people returns a predefined set of fields that reside in the 'root' (basic fields), 'about', 'employment', and 'work' categories. If a field is missing in the response when using the default query:

To learn more, see Categories and Permissions.

📘
Accessing historical data
When setting access to categories with historical information, setting 'view' access to the category will give you access only to the current entry, for example, the employee's effective work entry. To read the whole work history, you would need to use the tables endpoints, and set access also to the 'histories' data. To learn more, see Employee Tables.

Rate limiting

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. To learn more about rate limiting best practices, see Rate limiting.

Below is a table detailing the rate limits for each endpoint in the People's endpoints.

Method	Endpoint	Limit per minute
POST	Search for employees	50
GET	Read the public profile section of all active employees	40
POST	Read company employee fields by employee ID	100
PUT	Update company employee	10
POST	Create company employee	10
POST	Revoke access to Bob for an employee	50
POST	Terminate company employee	10
POST	Invite an employee with a welcome wizard ID	50
POST	Set or update an employee's start date.	20
GET	Read avatar for an employee email	20
GET	Read avatar for an employee ID	20
PUT	Upload employee's avatar by image url	10
PUT	Update an employee's email address	20