Connect HiBob

Connect HiBob so joiners, leavers, job and team changes, and pay changes reach Flowstate without anyone typing them in again. The forecast and budgets then work from the people you employ today.

You need access to integrations. Ask your Flowstate admin. First decide whether HiBob is where people changes are made: see Get your people data into Flowstate.

How it connects

Flowstate reads your people from HiBob’s API, signed in as a HiBob service user. We recommend a scheduled sync for HiBob: a service user gives read access without anyone’s personal login, and a run can read everyone along with their job and pay history. HiBob’s webhooks only say which employee changed, so the event-driven route still has to fetch the details from HiBob’s API.

Route	How it works	Choose it when
Scheduled sync (recommended)	A custom integration in Flowstate pulls from HiBob’s API on a schedule, from every 15 minutes to daily.	You want the sync to run inside Flowstate, with nothing of your own to host.
Event-driven	Your middleware, such as Workato, Boomi, MuleSoft, Make or n8n, receives HiBob’s webhooks and updates Flowstate through the REST API.	You already run middleware and want each change to arrive as it happens.

What you need from HiBob

A HiBob admin who can create service users and permission groups.
A service user, with its ID and token. HiBob only shows the token when it’s generated.
A permission group containing the service user, with:
- People’s Data → Access data for set to everyone you want in Flowstate. Anyone outside it is left out.
- View on the Root/Basic, Work, Employment and Lifecycle field categories.
- View history on the Work, Employment, Lifecycle and Salary tables. With View alone, HiBob returns only the current entry, not past changes.
- Features → Workforce planning → Position management → Manage positions, if you bring positions in as vacancies.
- Access to the category of any custom field you want synced.
For the event-driven route: webhooks set up in Bob, sending to your middleware.

Set it up

In HiBob

Create a service user, following HiBob’s service user guide.
Copy its ID and token.
Create a permission group, add the service user, and grant the access listed above.

In Flowstate

Ask your Flowstate contact to switch on custom integrations for your organisation. They provide the hook for HiBob and help your technical team configure it.
Go to Settings → Integrations → Custom Integrations: select Browse catalog and open Custom Integrations.
Select Create Integration. Enter a Name, such as HiBob, and a Source System Key, such as hibob. Select Create. You can’t change the key later.
Under Credentials, select Add Credential and store the service user’s ID and token, using the key name and format your Flowstate contact gives you.
Under Hooks, select Create Hook. Choose Pull as the Hook Type and Employee as the Entity Type, then select Create. Add the hook’s code and select Save Code. Add hooks for contractors and vacancies the same way if you bring them in.
On the hook’s Settings tab, turn on Run on schedule and choose an Interval. For Daily, choose a Preferred hour. Select Save Code.
Select Test (Dry Run) and open Preview. Check that nobody already in Flowstate is about to be created a second time.
Turn the hook on with the switch at the top of the editor, and confirm Enable Hook.

Each step in more detail: Manage a custom integration in Settings.

Event-driven instead

In Flowstate, go to Settings → Users & Access → API Keys and create a key that can view, create and update employees, contractors and vacancies.
In Bob, set up webhooks that send to your middleware. See HiBob’s webhook guide.
Your technical team has the middleware update Flowstate. See Sync people from an HR system with the REST API.

What syncs

HiBob	Flowstate
Employee ID	External ID, which is how the sync recognises the person on every run
First name, surname, email	Name and Email address
Job title	Role. A job title Flowstate hasn’t seen before adds a job role.
Department	Current team
Reports to	Line manager. A scheduled sync can’t set it: set it in Flowstate, or send it from middleware.
Employment type: Permanent, Temporary, Apprentice, Contractor, or your own types	Contractor employments come in as contractors, the rest as employees. Tell your Flowstate contact about any types you’ve added.
FTE percentage and weekly hours	FTE on their team
Start date, termination date and lifecycle status	Employment dates
Salary: base pay, currency, pay period and effective date	Salary changes, each from its effective date and in its own currency, on the Compensation tab
Workforce planning positions: status, department, expected start date and who fills them	Vacancies
Site	Location. A scheduled sync can’t set it: set it in Flowstate, or send it from middleware.
Not in HiBob	Work type (Employment type on the person’s record), which sets their overhead. Set it in Flowstate, or send it from middleware.

To set location, work type or line manager in Flowstate, go to Resourcing → People and teams → People, open the person and change them under Employee details. Nothing goes back to HiBob.

How changes arrive

When. On the schedule you chose, from Every 15 minutes to Daily. With the event-driven route, as HiBob sends each change.
Edits made in Flowstate. Anything the sync sends, such as role, team, dates and pay, is set back to HiBob’s value on the next run. Make those changes in HiBob. Location, work type and line manager stay as you set them. More in Edits made in Flowstate.
Leavers. A termination date in HiBob becomes the person’s end date in Flowstate. They stay in past months of the forecast and effort. The sync never deletes anyone. HiBob leaves inactive employees out of its lists unless it’s asked for them, so leavers must be included in every run.
Rehires. A returning employee keeps their old end date in Flowstate, because a sync can’t clear one. Your technical team clears it through the REST API. See Undo a leaver.
Future-dated pay. A pay change with a future effective date comes across on the next run and shows as Scheduled on the Compensation tab until that date.

Check it’s working

Open the hook and select Execution History.
Find the latest run with Scheduled under Triggered By. It shows Completed, with a count under Records.
If some records failed, the run’s log has a line for each one, with the reason.
Go to Resourcing → People and teams → People and compare a few people with HiBob: a recent joiner, a recent leaver (Filter → Status → Include off-boarded) and someone with a recent pay change. Check Role, Current team, Employment dates and the Compensation tab.

If something’s not right

Runs fail with an authentication error. The service user’s token was regenerated, or the service user was removed. Generate a new token, then update the credential. HiBob’s older API access tokens stopped working on 31 October 2024, so a service user is required.

Some people or details are missing. The service user’s permission group doesn’t cover them. People outside Access data for are left out, and HiBob drops fields the group can’t view without an error. Check the group’s access.

Only the current salary comes across, with no history. The permission group has View but not View history on the Salary table.

Runs fail with a 429 error. HiBob allows 50 people searches a minute. Choose a less frequent Interval, or ask your Flowstate contact to look at the hook.

For your technical team

API. https://api.hibob.com/v1. Sandbox: https://api.sandbox.hibob.com/v1.

Auth. Authorization: Basic base64({serviceUserId}:{token}). Hooks can’t Base64-encode, so store the encoded value as the credential. Service users start with no access and don’t count towards headcount. OAuth 2.0 is available only to approved HiBob Marketplace and technology partners.

Endpoints.

POST /people/search takes fields[] (at most 400), showInactive (send true to include leavers), humanReadable ("", APPEND or REPLACE) and filters (only root.id or root.email with equals). It isn’t paginated and has no changed-since filter. Fetch root.id for everyone first, then request batches of 50–200 IDs.
GET /bulk/people/work, /bulk/people/employment, /bulk/people/lifecycle and /bulk/people/salaries are cursor-paged (limit up to 200, cursor, response_metadata.next_cursor) and take employeeIds (up to 200). Entries carry effectiveDate, endEffectiveDate and isCurrent.
GET /company/people/fields lists fields with id, categoryId, type, typeData.listId, jsonPath and historical. It needs no permission.
POST /objects/position/search returns positions (/position/status, /position/department, /position/site, /position/employmentType, /position/expectedStartDate, /position/filledBy).
POST /hiring/job-openings/search returns job openings and is cursor-paged.

Fields.

Key on root.id.
In the work table, title and department are list IDs, not names. Check humanReadable or the company’s named lists to get the names.
Employment table: type (Permanent, Temporary, Apprentice, Contractor or custom), fte (FTE percentage, from the working pattern), weeklyHours, contract.
Salaries table: base{value, currency}, payPeriod (Annual, Hourly, Daily, Weekly, Monthly), payFrequency, effectiveDate, isCurrent.
Custom fields must be named in fields[].
Fields without permission are dropped with no error. Table endpoints set X-Has-Restricted-Columns: true when columns were filtered out.

Rate limits. People search allows 50 requests per minute. A 429 carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. Other endpoints have their own limits in each section of HiBob’s reference.

Webhooks, for middleware.

Webhooks v2 are configured in Bob, which shows the signing secret. v2 is the default; new v1 webhooks were disabled from 1 April 2025.
Employee events: employee.created, employee.updated, employee.deleted, employee.joined, employee.left, employee.activated, employee.inactivated, employee.temporary-leave. There are also table-entry created and updated events; check their exact names in HiBob’s reference.
Payloads carry IDs only (companyId, type, triggeredBy, triggeredAt, version, data.employeeId), so fetch the data from the API. employee.updated adds data.fieldUpdates[].id; bank-account and custom-table changes don’t fire it.
employee.left fires when the termination or garden-leave entry becomes effective, at midnight in the site’s time zone.
Verify Bob-Signature: Base64 of HMAC-SHA512 of the body, keyed by the secret.
HiBob retries for up to 3 days with exponential backoff, emails alerts at 1, 24, 48 and 72 hours, and deactivates the webhook after 72 hours of failures.
HiBob says to allow up to 20 seconds after an update before reading it back.
Map employee.left and employee.deleted to endDate in Flowstate. Don’t delete the person.

HiBob docs.