HiBob Integration Guide
Setyl integrates with HiBob to automatically import and sync employee data from HiBob into Setyl. This guide explains how to connect HiBob with Setyl, what permissions are required and which fields are synced.
What does the HiBob integration do?
The HiBob integration allows you to:
-
Automatically create users in Setyl based on HiBob records
-
Import your organizational structure including departments and locations
-
Automatically keep employee records up to date and accurate within Setyl
-
Trigger onboarding and offboarding workflows automatically within Setyl
What data is synced?
Setyl will sync the following employee data:
- First and last names
- Avatar/photo
- Department
- Location
- Legal entity
- Job title
- Join & leave date
- Phone number
- Address
- Employee ID
- Personal email
- Manager email
- Contract type
Note: You can configure data mapping for specific fields, including mapping data from multiple integrations. For more information on configuring data mapping, see the HR Integration Guide.
How often does the sync occur?
Employee data from HiBob will be synced once every 24 hours and once upon initial integration. Data can also be synced manually at any time by triggering a manual sync.
Setting up the HiBob integration
You can connect HiBob to Setyl in two ways. Both options sync the same data on the same schedule.
| OAuth | Service user (API token) | |
|---|---|---|
| How it works | Install the Setyl app from the HiBob Marketplace and approve access | Create a service user in HiBob and enter its credentials in Setyl |
| What you need in HiBob | Permission to install Marketplace apps | Permission to create service users and permission groups |
| Controlling who's synced | The employees you choose when you authorize | The Permission Group's Access data for setting |
Option 1: Connect with OAuth
Prerequisites
Before connecting, ensure that:
- You have permission to manage integrations in Setyl
- You have permission to install the Setyl app in your organization's HiBob account
Connect HiBob to Setyl
- In Setyl, navigate to Settings > Integrations. Find HiBob and open its connection settings.
(Tip: You can also start from HiBob. Open the Setyl app in your HiBob Marketplace and select Install. You'll be taken to Setyl, where you sign in and choose the company to connect.) - Select Connect with OAuth.
- In HiBob, review the requested employee data and sensitive employee data read permissions. Setyl uses these to read employee profiles, organizational information, employment dates, photos and employment type.
- Choose which employees Setyl can access, then select Authorize. Include everyone whose records Setyl should keep up to date, including future starters and leavers.
(Note: Setyl can't import employees or fields outside the access you grant here.) - When you're back in Setyl, wait for the data-access checks to finish.
(Note: The checks use a sample of employee and photo data, so an Available result doesn't guarantee access to every employee or field.) - Review Include inactive users and your data mappings. Choose HiBob as the source for the fields you want it to maintain.
- Click Save and Connect to finish the setup and start the first sync.
- Follow the sync progress, then review the imported or updated records under People.
Note: The sync can take longer when other background jobs are queued. Setyl only reads data from HiBob; it never edits HiBob employee profiles.
Switch from a service user to OAuth
If you already connect HiBob with a service user, you can switch without losing your settings:
- In Setyl, navigate to Settings > Integrations and open your existing HiBob connection.
- Select Switch to OAuth.
- Complete the authorization and access checks as described above.
Note: Keep your existing connection in place during the switch. Do not disconnect it first.
Reconnect or change authorized access
Use this if you need to change the permissions or the employees Setyl can access:
- If the Setyl app is still installed, uninstall it from your HiBob Marketplace.
- In Setyl, open the existing HiBob connection and select Reconnect with OAuth.
- Approve the permissions and choose the employees again.
Note: Do not select Disconnect in Setyl when reconnecting. Reconnecting keeps your integration settings and records. Syncing pauses between uninstalling the app in HiBob and finishing the reconnection.
Disconnect permanently
- Uninstall the Setyl app from your HiBob Marketplace.
- In Setyl, open the HiBob connection and select Disconnect.
Note: This stops future syncs. People already imported remain in Setyl.
Option 2: Connect with a service user (API token)
Prerequisites
Before connecting, ensure you have:
- A Setyl account with Owner-level admin permissions
- A HiBob service account user created with the required permissions
Step 1 — Create a service account in HiBob
To create a service account in HiBob, follow the official HiBob guide here: https://apidocs.hibob.com/docs/api-service-users
- Create a Service User in HiBob and add it to a dedicated Permission Group (service users have no access by default).
- Under Approved Scopes, select:
- Full employee read
- Employee fields read
- In the Permission Group → People’s data, grant View access to these categories:
rootworkhomepersonaladdressaboutinternalpayroll → employment
- Under Access data for, ensure the service user can view All employees (not just “Employed”), so that inactive or terminated employees are included when
showInactive: trueis used.
Step 2 — Connect HiBob to Setyl
- In Setyl, navigate to Settings > Integrations.
- Find HiBob and select Connect.
- Enter your Access Token and Service User ID from HiBob.
- Select Save & Connect.
- Once connected, data mapping options will appear. Map your preferred fields as needed.
- Click Save & Connect again to finalize the setup.
Note: It may take several minutes before data begins to sync after the connection has been made.
Troubleshooting and support
If your HiBob integration fails to connect (service user)
- Confirm your Access Token and Service User ID are correct.
- Disconnect and reconnect the HiBob integration.
- Contact Setyl Support for further assistance
If people or details are missing after connecting (service user)
- Some people, or leavers, are missing: in HiBob, open the service user's Permission Group and check that Access data for is set to All employees, not just "Employed". Otherwise Setyl can't see people who have left or haven't started yet, so their leave dates and statuses won't update.
- Some fields are blank, for example department, job title or manager: check that the Permission Group has View access to every category listed in Step 1.
- After changing permissions in HiBob, trigger a manual sync from Settings > Integrations.
If people or details are missing after connecting (OAuth)
- Some people or fields are missing: check which employees you authorized in HiBob, the Include inactive users setting in Setyl, and your data mappings.
- Select Check access again to see what Setyl can access. Checking access on its own doesn't import employees, so trigger a manual sync from Settings > Integrations afterwards.
- To change permissions or which employees Setyl can access, follow Reconnect or change authorized access above. Do not disconnect.
If HiBob says the app is already installed (OAuth)
- Uninstall the existing Setyl app in HiBob, then authorize again.
- If you're reconnecting, leave the HiBob connection in Setyl in place.
Additional resources
For more help, please visit our HR Integration Guide, explore one of our integration help pages, use the live chat at the bottom of the screen, or email us at hello@setyl.com.
View a full list of Setyl integrations.