--- updatedAt: 2026-05-25T08:45:34.000Z --- Fetch the complete documentation index at: https://apidocs.hibob.com/llms.txt. Use this file to discover all available pages before exploring further. # People 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](/reference/post_people-search) or [Read by ID](/reference/post_people-identifier) | [People read API contract](/docs/people-read-api-contract) — field IDs, permissions, filters, **no pagination**, **[batching for large companies](/docs/people-read-api-contract#recommended-pattern-for-large-companies-client-side-batching)**, silent omission, response shapes | | Step-by-step setup (metadata → permissions → API call) | [How to read employee data](/docs/how-to-read-employee-data) | | How employee data is modeled in Bob | [Explore Employee Data API](/docs/explore-employee-data) | > **Note:** People endpoints return employee **fields** only. For historical table rows (work history, salaries, etc.), use [Employee Tables](/reference/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**: * 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.](https://help.hibob.com/hc/en-us/articles/27875098648465-Manage-service-users#h_01JB9DYK9SZEJ7MF4DA7RHJE03)
**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](/reference/permissions). ## Troubleshooting For read-endpoint behavior (missing fields on `200 OK`, default field set, filter limits), see [People read API contract](/docs/people-read-api-contract). For permission setup and fields moved between categories, see [Categories and permissions](/docs/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 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](https://apidocs.hibob.com/reference/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](https://apidocs.hibob.com/docs/rate-limit). 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](https://apidocs.hibob.com/reference/post_people-search) | 50 | | GET | [Read the public profile section of all active employees](https://apidocs.hibob.com/reference/get_profiles) | 40 | | POST | [Read company employee fields by employee ID](https://apidocs.hibob.com/reference/post_people-identifier) | 100 | | PUT | [Update company employee](https://apidocs.hibob.com/reference/put_people-identifier) | 10 | | POST | [Create company employee](https://apidocs.hibob.com/reference/post_people) | 10 | | POST | [Revoke access to Bob for an employee](https://apidocs.hibob.com/reference/post_employees-identifier-uninvite) | 50 | | POST | [Terminate company employee](https://apidocs.hibob.com/reference/post_employees-identifier-terminate) | 10 | | POST | [Invite an employee with a welcome wizard ID](https://apidocs.hibob.com/reference/post_employees-employeeid-invitations) | 50 | | POST | [Set or update an employee's start date.](https://apidocs.hibob.com/reference/post_employees-employeeid-start-date) | 20 | | GET | [Read avatar for an employee email](https://apidocs.hibob.com/reference/get_avatars) | 20 | | GET | [Read avatar for an employee ID](https://apidocs.hibob.com/reference/get_avatars-employeeid) | 20 | | PUT | [Upload employee's avatar by image url](https://apidocs.hibob.com/reference/put_avatars-employeeid) | 10 | | PUT | [Update an employee's email address](https://apidocs.hibob.com/reference/put_people-id-email) | 20 |