A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The HiBob API is how an app or AI agent works with a Bob HR account: searching and reading employee records, updating fields and creating people, submitting and reading time off, and pulling reports and company lists. Access is authenticated as a service user, and what it can see or change is decided entirely by the permission groups that service user belongs to, with no per-endpoint scopes on top. HiBob can also push events to a webhook URL when an employee record changes.
How an app or AI agent connects to HiBob determines what it can reach. Calls are authenticated as a service user, and what that service user can see and change is set by the permission groups it belongs to.
The REST API answers at https://api.hibob.com/v1. It serves a single v1 API with no dated version header, and changes ship through the dated changelog.
HiBob's first-party MCP server lets an agent call Bob through the Model Context Protocol to read information and perform actions across people, time off, and tasks. It launched in beta on 28 April 2026, with the remote endpoint at https://mcp.hibob.com/mcp/public and a sandbox at https://mcp.sandbox.hibob.com/mcp/public. It authenticates with a Bob service user, so its reach is the same permission boundary as the REST API. The source is at github.com/hibobio/hibob-public-mcp.
Webhooks deliver the chosen employee events to a receiver URL configured in Bob, including scheduled changes that fire at midnight in the site timezone on their effective date.
An API service user is a non-login identity created in Bob to authenticate API calls. Its ID and token are joined with a colon, Base64-encoded, and sent in the Authorization header as Basic credentials. What it can read or change is set entirely by the permission groups it is added to, not by scopes on the token. This is the only supported method since 31 October 2024.
The legacy API access token authenticated calls as the admin who created it. New tokens could not be created after 31 May 2024, and the method was discontinued entirely on 31 October 2024 in favor of service users.
The HiBob API is split into areas an agent can act on, such as employee records, time off, tasks, documents, payroll, reports, and company lists. Each area reads or writes real people data, and the service user's permission groups decide which of it is reachable.
Search employees, create and update employee records, change a work email, terminate, invite, and set a start date.
Read and write an employee's employment and work history entries.
Read who's out, read a balance, and submit a new time off request.
List the company's open tasks, read one employee's tasks, and mark a task complete.
List an employee's documents and upload a shared document to their profile.
Read and write an employee's salary entries.
List the company's saved reports and download one as CSV, XLSX, or JSON.
Read the people fields metadata and read and write company named lists, such as departments and sites.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
People & employeesSearch employees, create and update employee records, change a work email, terminate, invite, and set a start date.8 | ||||||
| POST | /v1/people/search | Return chosen field data for many employees in one call, filtered by fields, filters, and audience. | read | People: view | Current | |
The service user needs view permission on each requested field's category, and the audience is limited to employees the permission group can see. Returns only currently employed people unless showInactive is set. Replaced the retired read-all and read-by-id endpoints. Acts onemployee Permission (capability) People: viewVersionAvailable since the API’s base version Webhook eventNone Rate limit50 requests per minute SourceOfficial documentation ↗ | ||||||
| POST | /v1/people/{identifier} | Read a single employee's field data by employee ID, email, or another identifier. | read | People: view | Current | |
Requires view permission on the requested field categories for an employee the permission group can see. Acts onemployee Permission (capability) People: viewVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/people | Create a new company employee from firstName, surname, email, and a work object. | write | People: edit | Current | |
Needs edit permission on the relevant people-data sections. Newly created data can take up to about 20 seconds to appear in a following read. Acts onemployee Permission (capability) People: editVersionAvailable since the API’s base version Webhook event employee-createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /v1/people/{identifier} | Update an existing employee's fields; only the fields sent are changed. | write | People: edit | Current | |
Needs edit permission on the field categories being changed. Returns 304 when nothing changed, so the right field IDs must be sent. Acts onemployee Permission (capability) People: editVersionAvailable since the API’s base version Webhook event employee-updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /v1/people/{id}/email | Update an employee's work email address. | write | People: edit | Current | |
Needs edit permission on the employee's contact section. Acts onemployee Permission (capability) People: editVersionAvailable since the API’s base version Webhook event employee-updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/employees/{identifier}/terminate | Terminate an employee, ending their employment. | write | People: edit | Current | |
Needs edit permission on the lifecycle section. Termination triggers the lifecycle webhook for an employee leaving. Acts onemployee Permission (capability) People: editVersionAvailable since the API’s base version Webhook event employee-leftRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/employees/{employeeId}/invitations | Send an employee an invitation to access Bob. | write | People: edit | Current | |
Needs edit permission on the employee. Granting access can fire the lifecycle event for an employee joining. Acts onemployee Permission (capability) People: editVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/employees/{employeeId}/start-date | Set or change an employee's start date. | write | People: edit | Current | |
Needs edit permission on the employment section. Acts onemployee Permission (capability) People: editVersionAvailable since the API’s base version Webhook event employee-updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Employment historyRead and write an employee's employment and work history entries.4 | ||||||
| GET | /v1/people/{id}/employment | Read an employee's employment history entries. | read | People: view | Current | |
Needs view permission on the employment section. Acts onemployment entry Permission (capability) People: viewVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/people/{id}/employment | Add a new employment history entry for an employee. | write | People: edit | Current | |
Needs edit permission on the employment section. Adding a row fires the table entry created webhook. Acts onemployment entry Permission (capability) People: editVersionAvailable since the API’s base version Webhook event table-entry-createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /v1/people/{id}/employment/{entry-id} | Update an existing employment history entry. | write | People: edit | Current | |
Needs edit permission on the employment section. Acts onemployment entry Permission (capability) People: editVersionAvailable since the API’s base version Webhook event table-entry-updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/people/{id}/work | Read an employee's work history entries, such as role, department, and site changes. | read | People: view | Current | |
Needs view permission on the work section. Acts onwork entry Permission (capability) People: viewVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Time offRead who's out, read a balance, and submit a new time off request.3 | ||||||
| GET | /v1/timeoff/outtoday | Read who is out of the office today or on a specified date. | read | Time off: view | Current | |
Returns only the people the service user is allowed to see. Private and hourly time off are excluded unless explicitly included. Acts ontime off Permission (capability) Time off: viewVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/timeoff/employees/{id}/balance | Read an employee's time off balance for a policy. | read | Time off: view | Current | |
Needs view permission on the employee's time off. Acts ontime off Permission (capability) Time off: viewVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/timeoff/employees/{id}/requests | Submit a new time off request for an employee. | write | Time off: edit | Current | |
Needs edit permission on time off. The body sets the policy type, range type, start and end dates, and can bypass approval or name an approver. Acts ontime off request Permission (capability) Time off: editVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
TasksList the company's open tasks, read one employee's tasks, and mark a task complete.3 | ||||||
| GET | /v1/tasks | List all open tasks for the company. | read | Tasks: view | Current | |
Needs the tasks feature permission. Returns open tasks the service user can see. Acts ontask Permission (capability) Tasks: viewVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/tasks-people/{id} | Read the open tasks for a specific employee. | read | Tasks: view | Current | |
Replaced the retired 'read my tasks' endpoint on 31 July 2024. Acts ontask Permission (capability) Tasks: viewVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/tasks/{taskId}/complete | Mark a task as complete. | write | Tasks: edit | Current | |
Needs edit permission on tasks. Acts ontask Permission (capability) Tasks: editVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
DocumentsList an employee's documents and upload a shared document to their profile.2 | ||||||
| GET | /v1/docs-people/{id} | List an employee's documents with their names and download links. | read | Documents: view | Current | |
Needs view permission on the employee's documents, or the call returns 403. Acts ondocument Permission (capability) Documents: viewVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/docs-people/{id}/shared/upload | Upload a shared document to an employee's profile. | write | Documents: edit | Current | |
Needs edit permission on the employee's shared documents. Acts ondocument Permission (capability) Documents: editVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Payroll & salariesRead and write an employee's salary entries.2 | ||||||
| GET | /v1/people/{id}/salaries | Read an employee's salary history entries. | read | Salaries: view | Current | |
Needs view permission on the salaries section, which is among the most sensitive people-data categories. Acts onsalary entry Permission (capability) Salaries: viewVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/people/{id}/salaries | Add a new salary entry for an employee. | write | Salaries: edit | Current | |
Needs edit permission on the salaries section. Adding a row fires the table entry created webhook. Acts onsalary entry Permission (capability) Salaries: editVersionAvailable since the API’s base version Webhook event table-entry-createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ReportsList the company's saved reports and download one as CSV, XLSX, or JSON.2 | ||||||
| GET | /v1/company/reports | List the company's saved reports and their details. | read | Reports: view | Current | |
Needs the reports feature permission. Acts onreport Permission (capability) Reports: viewVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/company/reports/{reportId}/download | Download a saved report as CSV, XLSX, or JSON. | read | Reports: view | Current | |
A report can return wide data across many employees, so its contents follow what the report was built on, not a narrow field filter. The format parameter selects csv, xlsx, or json. Acts onreport Permission (capability) Reports: viewVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Company lists & fieldsRead the people fields metadata and read and write company named lists, such as departments and sites.3 | ||||||
| GET | /v1/company/people/fields | Read the metadata for the company's people fields, including IDs and types. | read | Fields: view | Current | |
Used to discover the correct field IDs and JSON structure before reading or writing employee data. Acts onfield Permission (capability) Fields: viewVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/company/named-lists | Read the company's named lists, such as departments, sites, and other dropdown values. | read | Named lists: view | Current | |
Named lists are the configurable value sets behind company-wide dropdowns. Archived lists are excluded unless includeArchived is set. Acts onnamed list Permission (capability) Named lists: viewVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/company/named-lists/{listName} | Add an item to a company named list. | write | Named lists: edit | Current | |
Changes a company-wide value set used across many employee records. Acts onnamed list Permission (capability) Named lists: editVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
HiBob can notify an app or AI agent when something changes about an employee, instead of the app repeatedly asking. HiBob posts the event to a webhook URL that has been configured for the chosen events, including scheduled changes that fire at midnight in the site timezone on their effective date.
| Event | What it signals | Triggered by |
|---|---|---|
employee.created | Fires when an employee is created. | /v1/people |
employee.updated | Fires when one of an employee's fields is updated. | /v1/people/{identifier}/v1/people/{id}/email/v1/employees/{employeeId}/start-date |
employee.deleted | Fires when an employee is deleted. The payload includes the employee's email address for reference. | In-app only |
employee.joined | Lifecycle event that fires when an employee gains access to the system. | In-app only |
employee.left | Lifecycle event that fires when an employee is terminated or placed on garden leave. | /v1/employees/{identifier}/terminate |
table.entry.created | Fires when a new row is added to an employee's table, such as employment, work, or salary history. | /v1/people/{id}/employment/v1/people/{id}/salaries |
table.entry.updated | Fires when an existing table entry changes. Deleting a table entry does not trigger a webhook. | /v1/people/{id}/employment/{entry-id} |
HiBob limits how fast an app or AI agent can call, with a per-minute request quota set per service user that varies by endpoint, and a separate block on repeated failed authentication.
HiBob limits how many requests a service user can make per minute, and the limit is set per endpoint rather than as one global number. The employee search endpoint, POST /people/search, is documented at 50 requests per minute, and each section of the reference lists the limits for its own endpoints. Going over returns HTTP 429 Too Many Requests. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset, where reset is a Unix timestamp for when the window clears. A separate protection blocks an IP address for five minutes after more than 50 requests that return HTTP 401 from the same IP within ten seconds, so repeated failed authentication trips a temporary block.
Most list and search endpoints return all matching records in a single array rather than paging. The employee search endpoint returns every matching employee at once, filtered by the fields, filters, and audience set in the request body, so the result set is shaped by the request and the service user's access rather than by a page cursor.
Requests and responses are JSON. Report downloads can be returned as CSV, XLSX, or JSON through a format parameter, and document endpoints return download links rather than file bytes. Newly written employee data can take up to about 20 seconds to appear in a following read.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | Bad Request | The request is malformed or a parameter is invalid, such as an unknown field ID or an invalid time off policy. The body can include a structured message naming the invalid parameter. | Read the error message, correct the named field or parameter, and resend. Use the fields metadata endpoint to confirm the right field IDs. |
| 401 | Unauthorized | Authentication is missing or the service user ID and token are invalid. More than 50 such responses from one IP within ten seconds blocks that IP for five minutes. | Check the Base64-encoded service user ID and token in the Authorization header, then send valid credentials and avoid retry storms. |
| 403 | Forbidden | The service user is authenticated but its permission groups do not allow the requested data or action. | Add the service user to a permission group that grants the needed feature, people-data section, and employee audience. |
| 404 | Not Found | The endpoint path or resource does not exist, such as an unknown employee ID or report ID. | Confirm the path and identifiers are correct and that the resource exists. |
| 429 | Too Many Requests | The per-minute request limit for the endpoint and service user was exceeded. | Read X-RateLimit-Reset for when the window clears, then back off and retry. Prefer bulk endpoints over many single calls. |
| 500 | Internal Server Error | An unexpected error occurred on HiBob's side. | Retry after a short delay, and if it persists contact HiBob support. |
HiBob serves a single v1 API with no dated version string to pin. It evolves through dated changes in its changelog, where older endpoints are deprecated with a stated cutoff date and replaced.
HiBob serves one v1 API at https://api.hibob.com/v1 with no dated version header to pin. New capability and breaking changes both ship through the dated changelog, where an endpoint due for removal is announced ahead of time with a stated cutoff date and a replacement. An integration tracks the changelog rather than pinning a version.
The legacy API access token method was switched off on 31 October 2024, after new tokens stopped being issued on 31 May 2024. Service users became the only supported authentication method, where access is governed by permission groups rather than the creating admin's own rights.
The 'read my tasks' and 'read avatar for the logged-in user' endpoints were retired on 31 July 2024. They were replaced by endpoints that name the employee explicitly, such as reading tasks for a specific employee and reading an avatar by employee ID or email.
The 'read all company employees' and 'read company employee by ID' endpoints were deprecated and removed on 31 March 2024, in favor of the POST /people/search endpoint. Search returns the chosen fields for many employees in one call, filtered by an audience the service user is allowed to see, which gives more controlled access to employee data.
An integration pins nothing; it tracks the changelog for deprecations and their cutoff dates.
HiBob API changelog ↗Bollard AI sits between a team's AI agents and HiBob. Grant each agent exactly the access it needs, read or write, area by area, and every call is checked and logged.