Overview
Happl connects to HiBob using a service user: a dedicated, read-only API account that you create in HiBob. Setting it up takes around 15 minutes and has three parts:
Create the service user in HiBob and copy its ID and Token
Give the service user a permission group with the right access
Paste the ID and Token into Happl
Most connection problems come from Part 2. If the service user can't see a field, that field arrives in Happl blank, even though the connection shows as successful. Please follow the permissions step carefully and use the checklist at the end before you connect.
Before you start
You need Administrator permissions in your company's HiBob account (or ask a HiBob admin to complete Parts 1 and 2 for you)
Have somewhere secure ready to paste the Token. HiBob only shows the Token once. If you lose it, you'll need to generate a new one
Happl only reads data from HiBob. We never create, edit or delete anything in your HiBob account, even where a permission below is labelled "Edit"
Part 1: Create the service user in HiBob
In HiBob, go to System Settings
Open Integrations, then Service users (on some accounts this is a Service users tile with a Manage button)
Click Create service user
Enter a Display name such as Happl integration and click Create
HiBob now shows the service user's ID and Token. Copy both somewhere safe now, as you won't see the Token again. Then click Go to permission groups
Part 2: Give the service user the right permissions
A new service user has no access to anything until you add it to a permission group. There are three things to set: the group itself, whose data it can see, and which fields it can see.
2a. Create the permission group
Click Create permission group, then choose Service user
Enter a Group name such as Happl integration, select your new service user under Select service users, and click Create
When asked to confirm, click Confirm
2b. Choose whose data Happl can see
Important: don't leave this on Everyone. In HiBob, "Everyone" only covers active employees, so new starters who haven't started yet and leavers won't reach Happl.
In your new permission group, open the People's data tab and click Access data for
Click Edit permissions (top right)
Under Whose data can members access?, choose Select people by condition, then click Edit
Under Lifecycle status, tick Hired, Employed and Terminated, plus any custom statuses your company uses for people who should be in Happl (for example leave or garden leave). Click Apply, then Apply again
2c. Choose which fields Happl can see
Still in Edit permissions, go to People's data > People's fields
For each category in the table below, tick the permissions shown. You can set permissions on a whole category row (recommended) or on individual fields
Click Save, then Apply. The permissions aren't active until you've done both
Required for Happl
HiBob category | What Happl uses it for | Tick |
Basic info | First and last name | View, View history |
Work | Job title, work site/location, department, manager, start date | View, View history |
Employment | Employee ID, employment type, contract details | View, View history |
Work contact details | Work email (used to invite employees to Happl) | View |
Lifecycle | Employment status, termination date | View, View history |
Personal | Date of birth (used for age-based benefits and insurer data) | View, View history and Edit * |
Home | Gender | View |
Address | Home address | View, View history |
Payroll | Salary / pay rate, pay currency, pay frequency (used for salary-linked benefits such as life assurance and pension) | View, View history ** |
Recommended
HiBob category | What Happl uses it for | Tick |
Identification | National ID number, e.g. National Insurance number or SSN (needed by some insurers and providers) | View and Edit * |
* Why "Edit"? HiBob treats date of birth and national ID as sensitive, and only shares the full values (including the year of birth) with integrations that have both View and Edit. Without Edit, these fields will be blank or incomplete in Happl. Happl never writes to HiBob.
** Why "View history"? Pay details are stored in HiBob as a history table. Without View history on Payroll, salary information won't reach Happl.
You don't need to grant EEO (ethnicity), Financial (bank details), About, Equity or Time off. Happl doesn't use these, so you can leave them off.
Checklist before you connect
The service user is added to the permission group
Access data for is set to Select people by condition with Hired, Employed and Terminated ticked
All nine required categories are ticked, including View history where shown
Edit is ticked on Personal (date of birth), and on Identification if you're sharing national ID
You clicked Save and Apply
Part 3: Connect HiBob in Happl
In Happl, go to Settings > Integrations and click Connect in the HRIS section
Select HiBob from the list, choose Production Data, and follow the steps
When asked, paste in the service user ID and Token from Part 1
Your first sync then starts. Depending on the size of your company this takes from a few minutes to around an hour. When it's finished, check your data in Settings > Data Audit.
Troubleshooting
What you see in Happl | What to check in HiBob |
Connection works but most fields are blank | The service user isn't in the permission group, or the changes weren't saved. Reopen the group and click Save and Apply |
Date of birth is missing, or shows without a year | Add Edit on the Personal category (or on the Date of birth field) |
Salary, pay currency or pay frequency is missing | Add View and View history on Payroll |
Leavers or future starters are missing | Set Access data for to Select people by condition and tick Terminated and Hired |
National ID is missing or partly hidden | Add View and Edit on Identification |
A specific field is still missing | HiBob lets admins move fields into different categories. Open a sample employee's profile in HiBob, find which category the field is in, and grant View (and View history) on that category |
You've lost the Token | Generate a new Token for the service user in HiBob, then reconnect in Happl with the new one |
After changing permissions in HiBob, the missing data appears in Happl on the next sync. If anything is still missing after that, contact the Happl team through the chat and we'll help you check the setup.