The People API provides access to the details of your company employees.
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
Employee fields are organized within categories. With field-level permissions, grant access under People’s data > People’s fields at the category level or on individual fields. Prefer granting only the fields your integration needs.
Before accessing a field, ensure the service user has View (and Edit, when required) on that field or its category, just as you would with a user within Bob.
For example, to pull Personal contact fields, grant View under People’s fields > Personal contact details (category or specific fields).
| Permission type | Permission |
|---|---|
| Who to access | From People's data > Access rights > Edit:
|
| Read permissions | From People’s data > People’s fields, enable View on the category row and/or on specific fields. Example: |
| Read default fields in People search | To read basic employee data via the People search API, assign View on the root, about, employment, and work categories (or the specific fields you need in those categories). To learn more, see Permissions for |
| Read historical records (e.g. Work table with effective date) | From People’s data > People’s fields, enable View history on the historical table/category row (this permission is not available per field), and View on that table or the specific columns you need. Historical table rows appear in the UI with a (Table) label (for example Lifecycle (Table), Salary (Table)). Example: |
| Update permissions (e.g. terminate an employee) | From People’s data > People’s fields, enable Edit on the category/table row and/or on specific fields. Example: |
| Create new employees | From Features: People > Add new people to the company |
To learn more, see Permissions and Categories and permissions.
Troubleshooting
For read-endpoint behavior (missing fields on 200 OK, default field set, filter limits), see People read API contract. For permission setup, field-level access, 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(and field-level grants), not the field ID prefix.
Accessing historical dataWhen setting access under People’s fields, enabling View on a category or field gives access only to the current effective entry (for example, the employee’s current work entry). To read the full history via table endpoints, also enable View history on the category (not available per field). 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.