Bob's People API provides tools for searching, creating, updating, and retrieving employee data.
Getting started
| Goal | Guide |
|---|---|
| Integrate Search or Read by ID | People read API contract — field IDs, permissions, filters, no pagination, batching for large companies, silent omission, response shapes |
| Step-by-step setup (metadata → permissions → API call) | How to read employee data |
| How employee data is modeled in Bob | Explore Employee Data API |
Note: People endpoints return employee fields only. For historical table rows (work history, salaries, etc.), use Employee Tables.
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:
|
| Read permissions | From People’s data: Example: |
| 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 |
| Read historical records (e.g. Work table with effective date) | From People’s data: Example: |
| Update permissions (e.g. terminate an employee) | From People’s data: Example: |
| Create new employees | From People's data: People > Employees > Add new people to the company |
To learn more, see Permissions.
Troubleshooting
For read-endpoint behavior (missing fields on 200 OK, default field set, filter limits), see People read API contract. For permission setup and fields moved between categories, see Categories and permissions.
- Partial fetch or update — The API omits fields the service user cannot access; there is no explicit warning. Verify permissions against metadata
categoryId, not the field ID prefix.
Accessing historical dataWhen 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.