HiBob

HiBob (Bob)

This connector reads and updates the Bob HR platform by HiBob through its public REST API (https://api.hibob.com/v1): employee fields, work, employment, lifecycle and salary history, custom tables, company lists, time off (who is out, requests, balances, policies, holidays), saved reports, onboarding wizards, tasks and employee documents.

Setup (10 minutes, needs a Bob admin)

1. In Bob (as an admin) go to Settings > Integrations > Automation > Service Users, click Manage and create a service user with a name and display name. Copy its ID and token at once: the token is shown only when it is generated (a lost token can be regenerated, which invalidates the old one).
2. Create a dedicated permission group for the service user and add it there. A new group has no permissions, so grant only what you use:
   • People's data > People's fields: View on the categories you read (at least root, about, employment and work for hibob_search_people), View history on history tables (work, employment, lifecycle, payroll), Edit where you update.
   • Access data for: Everyone, or a condition. By default only employed people are covered; remove the condition Lifecycle status equals Employed to read leavers with show_inactive.
   • People's data > Time off: view requests and balances, and submit or cancel requests if you use those tools; view private requests for include_private.
   • Features > Reports: View reports according to people's data access rights.
   • People's data > Tasks and flow > People's tasks: View and mark selected people's tasks as complete.
   • People's data > Docs > [folder]: View (and Upload for the shared folder) per document folder.
3. Paste the ID into HIBOB_SERVICE_USER_ID and the token into HIBOB_SERVICE_USER_TOKEN. They are sent as HTTP Basic auth. hibob_list_employee_fields is the install check.

Workflow

• Field ids first: hibob_list_employee_fields lists every field with its id in dot notation (root.displayName, work.department, custom fields such as work.custom.field_123) and the list id of list fields. Company lists (hibob_list_named_lists, hibob_get_named_list) turn list ids into names (departments, sites, titles, calendars).
• People: hibob_search_people for many employees in one call (all, or filtered by root.id / root.email only; other filters are refused), hibob_get_employee for one person by id or email, hibob_list_profiles for a quick directory. For a large company, search with fields: ["root.id"] first and then read 50-200 ids per call.
• History tables: hibob_list_work_history (title, department, manager over time), hibob_list_employment_history, hibob_list_lifecycle_history, hibob_list_salary_history for one person; hibob_bulk_list_work_history, hibob_bulk_list_lifecycle_history and hibob_bulk_list_salary_history (payroll history) for many at once.
• Custom tables: hibob_list_custom_tables, hibob_get_custom_table_metadata, hibob_list_custom_table_entries.
• Time off: hibob_list_whos_out for a date range, hibob_list_out_today for one day, hibob_list_time_off_changes for what changed since a time, hibob_get_time_off_request for one request, hibob_get_time_off_balance for an employee's balance. Policies: hibob_list_policy_types, hibob_get_policy_type, hibob_list_policy_type_reason_codes, hibob_list_policy_names, hibob_get_policy. Holidays: hibob_search_calendar_events (an employee's calendar is payroll.employment.calendarId, or the default of the site in work.siteId).
• Booking time off: check hibob_get_policy_type for the unit, then hibob_submit_time_off_request; hibob_cancel_time_off_request cancels one.
• Reports: hibob_list_reports, then hibob_download_report (format json for readable rows). For large reports use hibob_request_report_download and fetch the file with hibob_download_report_by_name.
• Onboarding and tasks: hibob_list_onboarding_wizards, hibob_list_open_tasks, hibob_list_employee_tasks, hibob_complete_task.
• Documents: hibob_list_document_folders, hibob_list_employee_documents (download links), hibob_upload_shared_document.
• Writes to master data install switched off; turn them on deliberately in the connector: hibob_update_employee (fields only, not table rows), hibob_create_work_entry (promotion, transfer, new manager), hibob_create_custom_table_entry, hibob_add_named_list_item and hibob_upload_shared_document.

Reading the answers

• Employee ids are long numbers sent as strings (3332883884017713238). Requests use dot notation (work.department); responses use slash keys (/work/department) and may also nest the same value by category (work: {department: ...}).
• List fields hold item ids by default; pass human_readable: APPEND (or REPLACE) to also get the names.
• Silent omission: a field without permission or with a wrong id is simply missing from the answer (no error). When something is missing, check the permission group before concluding the value is empty.
• Dates are YYYY-MM-DD; hibob_list_time_off_changes takes ISO 8601 date-times. Balances are in the unit of the policy type (days or hours). Salaries carry their own currency.
• After an update Bob may return the old value for up to 20 seconds.

Paging: people search, profiles, history for one employee, open tasks (max 5,000) and who's out return everything at once. The bulk history tools and hibob_search_calendar_events page with cursor = response_metadata.next_cursor; stop when it is null.

Limits and errors: rate limits apply per endpoint (people search allows 50 requests per minute) and answer 429. 401 means a wrong ID or token, 403 a missing permission in the service user's group, 400 an invalid filter, field or date range (whos out and calendar ranges have maximum spans; time off changes reach back 6 months). Repeated 401 or 403 answers can be blocked for a while by Bob's firewall, so fix permissions before retrying.