HiBob

HiBob (often just called "Bob") is a modern HR platform used to manage the full employee lifecycle — people records and custom fields, time off and attendance, onboarding wizards, tasks, documents, and reporting. Because Bob is usually the system of record for who works where and who reports to whom, it is a natural anchor for HR, IT, and workplace automation.

This connector exposes Bob's public API so agents can look up employees and org structure, answer availability questions ("who is out next week?"), submit and cancel time off requests, drive onboarding and offboarding steps, and pull report data — all constrained by the permissions you grant the service user.

Authentication Types

This connector supports two authentication methods, but which one is available to you depends on who you are:

• API Key (service user) — recommended, and the only option for Bob customers building their own integration. A Service User ID and Token pair, sent as HTTP basic access authentication.
  • Pros: no marketplace approval needed, scoped by an explicit permission group, not tied to a real employee, and it never counts against headcount. You control exactly which data categories and which employees it can reach. Credentials do not expire.
  • Cons: the token is shown only once and must be regenerated if lost. Permissions live in Bob rather than in Willow, so expanding what an agent can do means editing the permission group.
• OAuth 2.0 — only for approved HiBob Marketplace and technology partners with an app registered in the HiBob Developer Portal.
  • Pros: the installing admin grants consent explicitly and picks which population the app may access, and no long-lived secret is stored.
  • Cons: requires partner approval from HiBob before you can get credentials. Access tokens expire after 5 minutes and refresh tokens must be used at least every 30 days or the connection has to be re-authorized. Bob also does not allow re-installing an app that is already installed — you must uninstall it from the Bob Marketplace before reconnecting.

note

If you are a Bob customer wiring up your own workspace, use API Key. HiBob does not issue OAuth credentials for customer-built integrations, and it discontinued the older "API Access Token" method, so service users are the only supported path. Conversely, HiBob does not allow Marketplace apps to authenticate with service users.

Setting up API Key

You need Bob Admin access to create a service user and its permission group. If you don't have it, ask a Bob Admin to complete steps 1–3 and hand you the credentials.

1. In Bob, open Settings → Integrations → Service Users and click Add service user.

2. Give it a descriptive name (for example Willow Integration) and generate the credentials. Copy both the Service User ID and the Token immediately — the token is displayed only once. If you lose it you must refresh the service user's token and update Willow.

3. Create a permission group for the service user, add the service user to it, and grant permissions. New groups start with no access at all, so nothing will work until you do this:

   • People's data — grant View all employees' [Category] sections for each category your tools read. To read basic employee data through the People search API, grant the Default Employee Fields permissions, which cover the root, about, employment, and work categories.
   • View history — to read table history (work, lifecycle, employment, salary entries), also grant View all employees' [Category] section histories. Without it you only get the currently effective row.
   • Edit — required to create or update employees, submit time off, complete tasks, or terminate someone. Also required for some sensitive fields even on read.
   • Features — enable the Bob areas you need, such as Reports, Time off, and Attendance.

4. Under Access rights → Access data for, choose whose data the service user may touch. By default this is limited to employees with Lifecycle status equals Employed. Remove that condition if your workflows need terminated, pre-hire, or on-leave employees — passing showInactive: true to a tool is not enough on its own.

5. In Willow, paste the credentials as a single value in the form SERVICE-USER-ID:TOKEN — the service user ID, a colon, then the token, with no spaces or line breaks. Willow base64-encodes the pair and sends it as Authorization: Basic <encoded>.

Setting up OAuth

This path requires an app in the HiBob Developer Portal, which HiBob grants to approved Marketplace and technology partners only.

1. Sign in to the Developer Portal and open your app, or create one from Basic information and choose an installation mode.

2. Under OAuth, add Willow's callback URL (shown in the Willow setup wizard) as the Redirect URI and click Save. Bob regenerates your app installation URL to include it.

3. Still under OAuth, select the scopes your app needs and save. Bob enforces scopes server-side, so a missing scope returns 403 even though the token is valid. This connector requests:

   Scope	Covers
   employee_data:read / employee_data:write	employee search and profiles, work/employment/lifecycle/salary history, avatars, create and update employees, invite, terminate, start date
   job_catalog:read	employee field metadata and named list items
   projects:write	named list index and onboarding wizards
   timeoff:read / timeoff:write	who's out, out today, balances, policies and policy types, submit and cancel requests
   tasks:write	open tasks, employee tasks, and completing a task (Bob groups these reads under :write)
   documents:read	employee documents and document folder metadata
   reports:read	report index and report downloads
   attendance:write	attendance entry search

   If the installing workspace has custom employee fields, Bob automatically adds custom_resources:write to the consent screen; it is not selectable in the scope picker.

4. Copy the Client ID and Client Secret into Willow. Use the Development pair while your app is unpublished and the Production pair once it is approved — a token minted with development credentials cannot be refreshed with production credentials, or vice versa.

5. Complete the consent flow from Willow. During consent the installing admin also chooses People data access, which decides whose records the app can reach. This selection is locked at install time: changing it later requires uninstalling and reinstalling the app, so pick an audience wide enough for your workflows.

warning

Bob's People data access layer filters on top of your scopes, so a valid token can still return partial results. A list call may return a subset of employees, and fetching an employee outside the selected audience returns 404 or 403 even though the scope is granted. Don't assume a successful response covers the whole organization.

Working with employee fields

Bob's data model is field- and category-based rather than a fixed employee schema, which shapes how several tools behave:

• Requests use dot notation (root.id, work.department), while responses use slash notation (/root/id). Use List Employee Fields to discover valid field IDs, their categories, and whether they keep history.
• Fields you lack permission for are silently omitted. A response with 200 OK can be missing fields you asked for, with no warning. Always check that the response contains what you requested before concluding a value is empty.
• Reads immediately after a write can be stale. Bob may return the previous value or null for up to 20 seconds after an update.
• Site, department, title, and termination reason are list-backed. Use List Company Lists and Get Company List to resolve the valid values or item IDs before writing.

Available Operations

The connector provides 39 tools:

• People (11) — search and read employees, list profiles, create, update, change email, terminate, set start date, invite, revoke access, and fetch avatars.
• Metadata and company lists (4) — employee field metadata, all named lists, a single named list, and onboarding wizards.
• Employee tables and history (6) — work, employment, lifecycle, and salary history per employee, a bulk cursor-paginated work history read, and creating work entries.
• Time off (10) — who's out over a range or today, get, submit, and cancel requests, balances, policy types, policy details, and a change feed for syncing.
• Tasks (3) — list open tasks company-wide, list one employee's tasks, and complete a task.
• Documents and reports (4) — employee documents, document folders, company reports, and report downloads.
• Attendance (1) — search an employee's attendance entries.

Troubleshooting

403 Forbidden on an endpoint that should work

Cause: The service user's permission group is missing the category permission, or the employee is outside its Access data for audience.

Solution: In Bob, open the service user's permission group and confirm both halves: the People's data permission for the specific category (plus section histories for table reads and Edit for writes), and that the employee falls inside the audience. Remember that a brand-new permission group grants nothing by default.

Fields are missing from the response, but the call returned 200

Cause: Bob silently drops requested fields when the service user lacks permission for their category, or when the field ID is invalid.

Solution: Run List Employee Fields and compare your field IDs against the id values it returns, using dot notation. Then grant the group View on the field's categoryId. Note that the category prefix in a field ID is not necessarily its current category — use the metadata categoryId when assigning permissions.

Terminated or pre-hire employees never appear in search results

Cause: showInactive defaults to false, and even with it set to true the permission group's audience is limited to employed people by default.

Solution: Pass showInactive: true and edit the permission group's Access data for setting to remove the Lifecycle status equals Employed condition.

401 Unauthorized right after setup

Cause: The credential was not entered as a colon-joined pair, or the token has been regenerated in Bob.

Solution: Re-enter the credential as exactly SERVICE-USER-ID:TOKEN with no spaces, quotes, or trailing newline — do not base64-encode it yourself, Willow does that. If the token was lost or rotated, refresh it in Bob's Service Users screen and update Willow.

OAuth: the connection worked, then started returning 401

Cause: HiBob access tokens expire after 5 minutes and refresh tokens must be exercised regularly. If the refresh token goes unused past its lifetime, it can no longer mint tokens.

Solution: Re-authorize the connection in Willow. Note that Bob does not support re-installing an app that is still installed — uninstall it first from Marketplace in Bob (open the app and click Uninstall), then reconnect.

OAuth: refreshing the token returns 401 well within the refresh window

Cause: Development and production credentials issue non-interchangeable tokens.

Solution: Confirm the Client ID and Client Secret in Willow come from the same environment as the one used to authorize — a token created with development credentials cannot be refreshed with production credentials, or vice versa.

OAuth: consent fails with a scopes or redirect URL error

Cause: Bob regenerates the app installation URL only after you save the scopes and redirect URI, so an app saved without them produces hibob.marketplace.error.bad.request.scopes.missing or ...redirect.url.missing.

Solution: In the Developer Portal, define at least one scope and the redirect URI, save each change, and then retry the connection from Willow.

An update returns 304 Not Modified

Cause: The Update Employee payload didn't change anything, usually because the field ID or the JSON nesting is wrong rather than because the value already matched.

Solution: Call Get Employee or Search Employees first and mirror the exact nested structure of the response in the fields object you send.

A time off request is rejected as invalid

Cause: The requestRangeType doesn't match the fields supplied, or the policy type is measured in a different unit than the request.

Solution: For days, send startDatePortion and endDatePortion. For hours, send hours and minutes, and make endDate equal to startDate — and only against a policy type measured in hours. For portionOnRange, send dayPortion. Use Get Time Off Policy Type to confirm the unit before submitting.

429 Too Many Requests

Cause: Bob rate-limits per endpoint and per account.

Solution: Back off and retry. Prefer bulk reads over loops: use Search Employees with a batch of IDs instead of repeated Get Employee calls, and List Work History In Bulk instead of per-employee history reads.

Additional Resources

• Bob Developer Hub
• API service users
• OAuth 2.0
• Scopes mapping to endpoints
• Authorization
• Permissions