> ## Documentation Index
> Fetch the complete documentation index at: https://docs.serval.com/llms.txt
> Use this file to discover all available pages before exploring further.

# HiBob

> Connect Serval to HiBob (Bob), the HR platform, so your workflows can read employee profiles, search people, and check time off on demand.

## 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

| Capability                        | Description                                                                                                                                                                                                                         |
| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Employee profiles and people data | Read employee profiles and your company's people-field definitions. Employees can be referenced by HiBob's internal ID or by their email address.                                                                                   |
| People search                     | Look up employees by their attributes, for example resolving someone's HiBob ID from their work email so a workflow can act on the right person.                                                                                    |
| Time off                          | Check an employee's remaining time off balance for a specific policy type as of a specific date, and list everyone who is out of the office today.                                                                                  |
| Installable workflows             | Employee self-service bundles for looking up profiles, finding coworkers, and managing time off (see below).                                                                                                                        |
| Full HiBob API access             | Workflows are not limited to the capabilities above - they can reach any part of the HiBob Public API your service user is permitted to use, including areas such as attendance, tasks, documents, reports, and workforce planning. |

Anything defined in the [HiBob API](https://apidocs.hibob.com/) can be accessed through Serval.

## Installable workflows

Each workflow identifies the requesting employee automatically from their email.

| Bundle        | Workflows                                                                                                                               |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| **Directory** | **Get My HiBob Profile** and **Find a HiBob Coworker** - look up your own profile or a coworker's title, department, site, and manager. |
| **Time Off**  | **Check My Time Off Balance in HiBob**, **List Who's Out in HiBob**, and **Request Time Off in HiBob**.                                 |

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](https://apidocs.hibob.com/docs/api-service-users) covers the same process in more detail.

<Note>
  HiBob discontinued its legacy API Access Token method on October 31, 2024. Service Users are the only supported way to connect.
</Note>

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.

    <Warning>
      The Token is displayed only once. If you lose it, you must regenerate it in HiBob.
    </Warning>
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Tip>
  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.
</Tip>

## Connect in Serval

<Steps>
  <Step title="Open the HiBob connect form">
    In Serval, add the **HiBob** integration to open the connect form.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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)".
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Note>
  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.
</Note>

## 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."

<Tip>
  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.
</Tip>

## Gotchas and troubleshooting

<AccordionGroup>
  <Accordion title="403 'token not match' errors usually mean the wrong environment">
    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.
  </Accordion>

  <Accordion title="Switching the environment changes the connection's identity">
    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.
  </Accordion>

  <Accordion title="New service users have zero permissions">
    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.
  </Accordion>

  <Accordion title="Time off calls fail even though profile checks pass">
    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.
  </Accordion>

  <Accordion title="The token is shown only once in HiBob">
    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.
  </Accordion>

  <Accordion title="Rotating or updating credentials">
    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.
  </Accordion>

  <Accordion title="Service users only see active employees by default">
    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.
  </Accordion>

  <Accordion title="Fields vary between HiBob accounts">
    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.
  </Accordion>
</AccordionGroup>

***

Need help? Contact **[support@serval.com](mailto:support@serval.com)** for assistance with your HiBob integration.