Skip to main content

​
About HiBob

HiBob (also called Bob) is an HR platform (HRIS) that holds your organization’s employee data, profiles, and time off records. Serval connects to a single HiBob account through a HiBob Service User - an API-only account you create in HiBob. Once connected, your Serval workflows can read people data and time off information from HiBob whenever they run. Serval supports both HiBob environments - production (api.hibob.com) and sandbox (api.sandbox.hibob.com). Each connection routes its API calls to the environment you selected when connecting, and credentials are only ever sent to these two HiBob API hosts. Authentication: HiBob Service User (a Service User ID and Service User Token, stored together as one credential). There is no OAuth flow. Data sync: On-demand only. Workflows call the HiBob API at the moment they run. There is no background sync, no data ingestion, no webhooks, and no event triggers.

​
What the HiBob integration enables

Anything defined in the HiBob API can be accessed through Serval.

​
Installable workflows

Each workflow identifies the requesting employee automatically from their email. Read-only workflows run without approval by default. Request Time Off in HiBob writes back to HiBob and requires approval by the installer by default.

​
Get your credentials

Serval authenticates with a HiBob Service User: an API-only account that is not tied to a real employee and cannot log in to Bob. Creating one gives you a Service User ID and a Token, and you control exactly what it can access through a HiBob Permission Group. HiBob’s official API Service Users guide covers the same process in more detail.
HiBob discontinued its legacy API Access Token method on October 31, 2024. Service Users are the only supported way to connect.
1

Create the service user

Log in to HiBob as an Admin and go to Settings > Integrations > Service Users, then click Add Service User. If you don’t see the Service Users option, ask your HiBob administrator to grant you the necessary permissions.
2

Copy the ID and Token immediately

Give the service user a descriptive name (for example “Serval Integration”), click Create, and copy both the Service User ID and the Token right away.
The Token is displayed only once. If you lose it, you must regenerate it in HiBob.
3

Create a Permission Group

Go to Settings > Account > Permission Groups and click Add Permission Group. Name it something descriptive (for example “Serval API Access”). New service users have no permissions at all by default.
4

Add the service user to the group

Add the service user to the new group, and keep the group scoped to only the permissions your Serval workflows require.
5

Grant the permissions your workflows need

Edit the group’s permissions. Under Features, enable the areas of Bob you need (for example Reports for reporting). Under People’s Data, grant access per category: “View” permissions for reads, “View histories” for historical data such as lifecycle or work table entries, and “Edit” for updates or sensitive fields. For basic people search access, assign the Default Employee Fields permissions, which cover the root, about, employment, and work categories.
6

Choose whose data the service user can see

Under People’s Data, use Access data for to choose Everyone, Select by condition, or Select by name. By default service users can only access active employees; to include inactive employees, edit the access conditions and remove the “Lifecycle status equals Employed” filter.
If your workflows will check time off balances or who is out today, make sure the group also includes Time off API permissions - these are separate from people-data permissions.

​
Connect in Serval

1

Open the HiBob connect form

In Serval, add the HiBob integration to open the connect form.
2

Choose the environment

Environment (required) - select Production (api.hibob.com) or Sandbox (api.sandbox.hibob.com). Defaults to Production. Pick the environment the service user was created in: a sandbox service user only authenticates against the sandbox API, and a production service user only against production.
3

Enter the Service User ID

Service User ID (required) - a text field with the helper text “Your HiBob API Service User ID”. If it is left blank, the form shows “This field is required” and will not submit.
4

Enter the Service User Token

Service User Token (required) - a password field with the helper text “Your HiBob API Service User Token”. The form does not check the Token as you type, so paste it carefully; submitting without one fails with the error “Failed to install integration (HTTP 500)”.
5

Save the connection

Serval stores the ID and Token together as a single credential and uses it for every call your workflows make to HiBob. The Basic Authentication encoding is handled automatically - enter both values exactly as HiBob displayed them.
When you edit an existing connection, the Service User ID appears in full and the Token appears as a masked value - dots plus its last four characters - that you can’t type into directly. To enter a new Token, click Replace (on the reconnect form) or the pencil icon (on the connection settings page) and paste the new value. Serval keeps your existing credentials whenever the Token is left untouched or either field is blank on save - the credential is replaced only when both fields are filled in. Because the two values are stored together as one credential, an edit that changes only the Service User ID does not take effect; re-enter the Token whenever you change the ID.

​
Verifying the connection

Serval ships three health checks for HiBob. Each one calls the live HiBob API when it runs. Test HiBob Connection - verifies the credential can reach the HiBob API by reading your company’s people-field definitions.
  • Success: “Successfully connected to HiBob API and retrieved [number] people fields”
  • Failure: “Unable to connect to HiBob. Please verify your Service User ID and Token have the required permissions.”
List HiBob Employee Profiles - reads employee profiles and reports how many were returned.
  • Success: “Successfully listed employee profiles from HiBob (count: [number])”
  • Failure: “Unable to list employee profiles from HiBob. Please verify your Service User ID and Token have the required permissions.”
List HiBob Employees Out Today - reads the list of employees out of the office today, which specifically exercises the Time off API permission.
  • Success: “Successfully retrieved time off data from HiBob ([number] employees out today)”
  • Failure: “Unable to retrieve time off data from HiBob. Please verify your Service User ID and Token have the required permissions for the Time off API.”
A service user can pass the connection and profile checks while still failing the out-today check, because Time off API access is a separate permission in HiBob. If only the time off check fails, add Time off permissions to the service user’s Permission Group.

​
Gotchas and troubleshooting

HiBob issues separate service users for production and sandbox, and each one only works against its own host. If every API call fails with a 403 error like “token not match”, check that the connection’s Environment matches where the service user was created - a sandbox service user used with the Production environment (or vice versa) fails this way. Edit the connection, switch the Environment, and re-run the health checks.
The environment is part of a connection’s identity. If you switch an existing connection from Production to Sandbox (or back), workflows that were bound to the old environment’s instance stop resolving it and fail at the start of their next run until you switch back or update the workflow’s app binding. If you need both environments at once, keep two separate connections - for example your production connection in your main workspace and a sandbox connection in a testing workspace - instead of flipping one connection back and forth.
A freshly created HiBob service user can authenticate but cannot read anything until it is added to a Permission Group with the right category permissions. In Serval this shows up as failing health checks that ask you to verify the Service User ID and Token have the required permissions. Grant the permissions in HiBob, confirm the service user has not been deleted or deactivated, then re-run the health checks.
Time off requires its own Time off API permission in HiBob, separate from people-data permissions. A service user can read profiles successfully while every time off call fails - the time off health check failure message calls this out explicitly. Add Time off permissions to the service user’s Permission Group.
HiBob displays the Service User Token a single time, at creation. Serval stores it masked (dots plus the last four characters) - it can be replaced but never revealed. If the token is lost, regenerate it in HiBob, then update the Serval connection: click Replace on the Token field, paste the new Token, and save.
There is no automatic token refresh or expiry handling - rotation is always manual through the connection’s edit form. The Service User ID stays filled in on the edit form, so replacing just the Token rotates the credential in one step. Leaving either field blank on save keeps your existing stored credentials unchanged, and a change to the Service User ID only takes effect when a Token is entered along with it.
HiBob filters a service user’s data access to active employees (the “Lifecycle status equals Employed” condition). Workflows that need offboarded or pre-start employees require editing the Permission Group’s Access data for conditions in HiBob to remove that filter.
People data includes custom fields defined per organization, so the exact field set differs from one HiBob account to another. Employees can also be referenced by either HiBob’s internal ID or their email address - helpful to know when a workflow asks for an employee identifier.
Need help? Contact support@serval.com for assistance with your HiBob integration.