canonical: https://jentic.com/apis/hibob.com/hibob

# Hibob Bob API

The Bob API is HiBob's HR platform interface for managing employees, onboarding, time-off, attendance, reports, and company configuration. Across 94 endpoints, integrators can search and read employees, create and terminate employees, set start dates and welcome wizards, manage avatars and tasks, configure custom fields and named lists, submit and inspect time-off requests, query who's-out today, and import attendance. Authentication accepts a Bearer-style API token in the Authorization header or HTTP Basic for service users, and a sandbox host (api.sandbox.hibob.com) is available for testing.

## For AI agents

Manage HiBob employees, onboarding, time-off, attendance, custom fields, and reports through 94 endpoints with token or Basic authentication, including a sandbox host.

## Scope

Does not handle payroll processing, benefits enrollment, or applicant tracking - use for HiBob employee records, time-off, attendance, and HR reports only.

## Capabilities

- Search employees with rich filters via POST /people/search and read details via GET /people/{identifier}
- Create, update, terminate, and uninvite employees through the /people and /employees endpoints
- Onboard new hires by setting start dates and sending welcome wizards via POST /employees/{employeeId}/invitations
- Submit, retrieve, and cancel time-off requests and read who's-out lists for a given date
- Manage company-level reports - list, download synchronously, or download asynchronously by report id or name
- Define and update custom employee fields and named company lists used as picklists across the platform
- Import attendance data in bulk via POST /attendance/import/{importMethod} for time-tracking integrations

## Use cases

### Joiner-Mover-Leaver Automation

HRIS automations create new employees with POST /people, set their start date via POST /employees/{employeeId}/start-date, and trigger welcome wizards through POST /employees/{employeeId}/invitations. When someone leaves, POST /employees/{identifier}/terminate handles the termination workflow and POST /employees/{identifier}/uninvite revokes Bob access. This collapses what is typically a multi-tab UI process into a single workflow.

Example prompt: Call POST /people to create the employee, then POST /employees/{employeeId}/invitations with welcome wizard id 42, then POST /employees/{employeeId}/start-date with the agreed date.

### Time-Off Coordination

Workforce planning agents read who's-out via GET /timeoff/whosout and GET /timeoff/outtoday, then submit time-off requests with POST /timeoff/employees/{id}/requests when an employee asks via Slack or chat. Balance enquiries through GET /timeoff/employees/{id}/balance let the same agent confirm policy entitlements before submitting.

Example prompt: Call GET /timeoff/employees/1234/balance to confirm vacation balance, then POST /timeoff/employees/1234/requests for the requested dates.

### Reporting Pipeline

Analytics teams trigger HR reports via GET /company/reports to discover available reports, then GET /company/reports/{reportId}/download or its async variant to fetch the file. The async download polling pattern handles large reports without blocking the request, ideal for warehouse loaders that ship daily or weekly headcount data.

Example prompt: Call GET /company/reports/{reportId}/download-async, poll the returned URL until the file is ready, then push the contents to a data warehouse loader.

### AI Agent HR Operations

Through Jentic, an AI assistant can answer 'how many people are out today?' or 'what's John's start date?' by calling Bob's read endpoints, and submit time-off requests for an employee on demand. Jentic's vault holds the API token, so the agent operates on HR data without seeing the raw credential - important for SOC-2 controls.

Example prompt: Search Jentic for 'who is out of the office today', execute GET /timeoff/outtoday, and return the list as a Slack-friendly summary.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /people/search | Search employees with rich filters |
| POST | /people | Create an employee |
| POST | /employees/{employeeId}/invitations | Send a welcome wizard invitation |
| POST | /employees/{identifier}/terminate | Terminate an employee |
| POST | /timeoff/employees/{id}/requests | Submit a time-off request |
| GET | /timeoff/whosout | List employees out of the office on a given date |
| GET | /company/reports/{reportId}/download-async | Async download URL for a large HR report |

## Key resources

- **People** — Search, read, create, update, and terminate employee records
- **Employees** — Onboarding actions including invitations, start dates, and termination
- **Time Off** — Submit, cancel, and inspect time-off requests, balances, policies, and out-of-office lists
- **Company Reports** — List and download HR reports synchronously or asynchronously
- **Tasks** — Read open tasks, list tasks for a person, and mark tasks complete
- **Custom Fields and Lists** — Define company-level employee fields and named picklists
- **Attendance** — Import attendance data in bulk for time-tracking integrations

## Why Jentic

- **Setup:** Wiring the Bob API by hand means supporting two auth shapes at once, a Bearer service-user token in the Authorization header and Basic credentials, and choosing between the production and sandbox hosts. Through Jentic you install once, import the Bob API from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Bob puts the employee id in the URL path (/employees/{employeeId}/invitations, /timeoff/employees/{id}/requests), so a rule can pin your agent to one employee record and the operations around it. You choose the operations it may call, so destructive ones like terminating an employee or deleting a time-off request are not included unless you add them.
- **Credential handling:** Your Bob service-user token and Basic credentials are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create an employee' or 'who is out today', and Jentic returns the matching Bob operation with its input schema so the agent calls the right endpoint without scanning the HiBob reference docs.

## Related APIs

- **BambooHR API** — BambooHR offers comparable HRIS functionality including employee records, time-off, and reports
- **Rippling API** — Rippling unifies HR, IT, and finance with broader app provisioning and device management
- **Gusto API** — Gusto handles US payroll and benefits and pairs well with HiBob's employee record system

## FAQ

### What authentication does the Bob API use?

The Bob API supports two schemes: a service-user token passed as Authorization: Bearer <token> (the Bearer scheme in the spec is implemented as an apiKey-style header), or HTTP Basic for service users. Tokens are generated under HiBob's automation users. Through Jentic, both credential types live in the encrypted vault and are injected at execution time.

### Can I create and onboard a new employee with the Bob API?

Yes. POST /people creates the employee record; POST /employees/{employeeId}/start-date sets or updates the start date; POST /employees/{employeeId}/invitations sends a welcome wizard. The three calls together handle the onboarding flow that is otherwise multiple screens in the Bob UI.

### How do I download a HiBob report through Jentic?

Run pip install jentic, search for 'download a hibob report', and choose between GET /company/reports/{reportId}/download for synchronous downloads or GET /company/reports/{reportId}/download-async for large files. Jentic resolves the auth header from the vault.

### Is there a sandbox environment for the Bob API?

Yes - the spec lists https://api.sandbox.hibob.com/v1 as an alternate server. Use it for development and integration testing before pointing your integration at https://api.hibob.com/v1 in production.

### How do I list employees who are out today?

Call GET /timeoff/outtoday for the current day or GET /timeoff/whosout with a date parameter for a specific date. Both return the list of employees on time off so an agent can build an out-of-office digest without reading individual time-off records.

### What are the rate limits for the Bob API?

HiBob enforces per-token rate limits that are not published in the spec but are returned through HTTP 429 responses. Implement backoff on 429 responses and prefer the async report download endpoints for any payload over a few megabytes to avoid tying up request slots.

### Can I limit what my agent is allowed to do with the Bob API?

Yes. Because Jentic One is self-hosted, your own rules decide which Bob operations and credentials the agent may use, so you can allow read-only calls like GET /timeoff/whosout while withholding destructive ones such as POST /employees/{identifier}/terminate unless you explicitly add them. Bob also carries the employee id in the URL path, as in /employees/{employeeId}/invitations and /timeoff/employees/{id}/requests, so a rule can pin the agent to a single employee record and the operations around it. The service-user token or Basic credentials stay with your instance and are injected at execution time, never entering the agent's prompt or logs.