> For the complete documentation index, see [llms.txt](https://docs.docontrol.io/docontrol-user-guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.docontrol.io/docontrol-user-guide/integrations/hris/hibob.md).

# HiBob

### Overview

The DoControl–HiBob integration lets DoControl read your employee roster directly from Bob so that every user and access finding DoControl surfaces is tied to a real person: their name, work email, department, manager, job title, and employment status (active, inactive, or terminated). This is what lets DoControl, for example, automatically flag a SaaS account that is still active after HiBob marks its owner as terminated, or group findings by department for the right manager to review. 

To do this, DoControl requests two HiBob OAuth scopes: 

| **Scope**             | **Why DoControl needs it**                                                                                                                                                                                                                  |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| employee\_data:read   | Read employee profile data (name, email, department, manager, title, employment status/dates) so SaaS access findings can be attributed to a real employee and their current employment status. Portal label:  People > View employee data. |
| company.metadata:read | Read the company's department list so employees and findings can be grouped and labeled by department. Portal label: Settings > View company metadata.                                                                                      |

DoControl does not request write access, and does not create, update, or delete anything in Bob. The integration is read-only. 

When you install the app, HiBob's consent screen also lets you choose which employees' data DoControl can read (People data access / audience). DoControl recommends granting access to your full employee population so that offboarding and department-based findings stay accurate; scoping to a subset means employees outside that scope will not appear in DoControl. 

### Installation steps 

DoControl's HiBob app uses OAuth 2.0, and the connection must be started from DoControl — installing directly from the Bob Marketplace listing (the Install button on Bob's side) is not supported; that entry point is intentionally blocked. Always start from DoControl as described below. 

1\.  Log in to DoControl and open the Integrations page (Data governance tab). 

<figure><img src="https://3236294211-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MesrnyDMZGYg1V-tOBo%2Fuploads%2Fhpn721gcO1HysiwryPq9%2FScreenshot%202026-09-28%20at%201.39.23%E2%80%AFPM.png?alt=media&amp;token=7bff6862-935a-4325-9cc4-764d2c44504c" alt=""><figcaption></figcaption></figure>

2\. Filter by category HRIS (or search "HiBob"), locate the HiBob tile, and click Connect. &#x20;

3\.  You're redirected to Bob. If you're not already logged in to Bob, you'll be asked to log in first (email + password, or Google / Microsoft SSO). &#x20;

<figure><img src="https://3236294211-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MesrnyDMZGYg1V-tOBo%2Fuploads%2FXL7dwYDdVxCBH9TsiwKA%2FScreenshot%202026-09-28%20at%201.39.53%E2%80%AFPM.png?alt=media&amp;token=83c7897b-cd02-41f4-bbf6-ba9bb0ba660a" alt=""><figcaption></figcaption></figure>

4\. Bob shows its **App permissions** screen: the scopes DoControl is requesting — **View employee data (employee\_data:read)** and V**iew company metadata (company.metadata:read)** — and **People data access**, whose data DoControl can read. Choose **All company, Select by condition**, or **Select by name.** &#x20;

*The screenshot below was captured before company.metadata:read was added to the listing, so it only shows one permission line. Re-capture this once the updated listing is live so it shows both.*&#x20;

<figure><img src="https://3236294211-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MesrnyDMZGYg1V-tOBo%2Fuploads%2FwN3zh8GkBPygyifmI3lm%2FScreenshot%202026-09-28%20at%201.43.15%E2%80%AFPM.png?alt=media&amp;token=e9f781c7-8f19-4561-96ff-af4b4f7920a0" alt="" width="375"><figcaption></figcaption></figure>

DoControl recommends **All company** so offboarding and department-based findings stay accurate; employees outside the chosen scope will not appear in DoControl.&#x20;

5\. Click **Authorize**. Bob redirects you back to DoControl, and the HiBob tile updates from **Connect** to **Connected**. The first sync starts automatically (see Data sync flows). &#x20;

<figure><img src="https://3236294211-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MesrnyDMZGYg1V-tOBo%2Fuploads%2FFIZh7PgBtmFnjOWtwJ3g%2FScreenshot%202026-09-28%20at%201.47.27%E2%80%AFPM.png?alt=media&amp;token=0d95895f-f157-4234-9003-53dfa93026f0" alt=""><figcaption></figcaption></figure>

There's nothing further to configure in Bob or in DoControl once you've clicked **Authorize**.&#x20;

### Setup in DoControl&#x20;

Once connected, HiBob requires no further configuration in DoControl. A few things to know:&#x20;

•  **Connection status** is always visible on the Integrations page: a green Connected label on the HiBob tile means DoControl currently holds a valid token and the last sync succeeded.&#x20;

•  **Where the data shows up:** synced employees appear under **Inventory** → **Users**, filterable by source "HiBob." Departments synced from HiBob are used to group and filter users and findings throughout the product.&#x20;

•  **Reconnecting**: if HiBob tokens are revoked (for example, after uninstalling the app in Bob, or after a long period without any HiBob activity), the tile shows **Disconnected**. Click **Connect** again from DoControl and repeat the steps above — no data is lost, and the next sync picks up where reporting left off.&#x20;

•  **Disconnecting**: clicking **Disconnect** in DoControl, or uninstalling the DoControl app from Bob Marketplace, immediately revokes DoControl's stored token and stops all syncing. Previously synced data is retained in DoControl until the integration is reconnected or the data is separately purged per your data retention settings.&#x20;

### Data sync flows&#x20;

**Initial sync (runs immediately after you approve the consent screen):**&#x20;

•  DoControl calls HiBob's People API (POST /v1/people/search) to pull your employee roster, including both active and inactive/terminated employees, with the fields DoControl needs: name, work and personal email, job title, department, manager, employment start date, termination date, employment status, and profile photo.&#x20;

•  DoControl calls HiBob's named lists API (GET /v1/company/named-lists/department) to pull your department list, used to label and group employees by department.&#x20;

•  A first-connection health check confirms both calls return data before the integration is marked  Connected; if either returns nothing (for example, an audience scoped to zero employees, or a company with no departments configured), the connection is flagged so you can widen the People data access audience in Bob.&#x20;

#### Ongoing sync:&#x20;

•  DoControl subscribes to HiBob's Webhook v2 employee events, so employee creations, joins, updates, and terminations/departures reach DoControl in near real time — there is no fixed polling interval to wait out for a change to show up.&#x20;

•  DoControl also refreshes its full roster and department list periodically as a background reconciliation pass, independent of webhook delivery.&#x20;

• Access tokens are short-lived (about 5 minutes) and refreshed automatically by DoControl using the refresh token issued at connect time. This requires no action from you; if a refresh fails (for example, the installation was removed in Bob), the integration shows as **Disconnected** and needs to be reconnected per Setup in DoControl.&#x20;

DoControl never writes back to HiBob — every call above is a read.&#x20;

### Troubleshooting&#x20;

| **Symptom**                                                                                                           | **Likely cause**                                                                                                               | **What to do**                                                                                                                                                                   |
| --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <p>HiBob tile shows  </p><p>Disconnected shortly after connecting</p>                                                 | The app was uninstalled or tokens were revoked in Bob                                                                          | Click **Connect** again and re-approve the consent screen                                                                                                                        |
| <p>No employees appear under Inventory → Users after </p><p>connecting</p>                                            | <p>People data access </p><p>(audience) was scoped too narrowly during install, or the account has zero employees in scope</p> | In Bob, review the app's People data access under **Marketplace** → **Manage apps**, widen the audience, then reconnect                                                          |
| Departments are missing or show as raw IDs instead of names                                                           | The HiBob account has no departments configured, or the department named list hasn't synced yet                                | Confirm departments exist in Bob under Company settings; allow a few minutes and refresh; contact support if it persists                                                         |
| New hires or terminations aren't reflected quickly                                                                    | <p>Webhook delivery is delayed or was temporarily </p><p>unavailable</p>                                                       | DoControl's periodic reconciliation sync will pick up the change on its next pass; contact support if a specific employee is still missing after 24 hours                        |
| Reconnecting doesn't clear the Disconnected status                                                                    | <p>Browser blocked the Bob </p><p>redirect, or the consent </p><p>screen was closed before approving</p>                       | Retry the **Connect** flow in a standard browser window and complete the Bob consent screen fully                                                                                |
| <p>Clicking Install on the </p><p>DoControl listing inside Bob Marketplace doesn't </p><p>complete the connection</p> | <p>Installing directly from the Bob Marketplace is not a </p><p>supported entry point for this app</p>                         | <p>Start the connection from DoControl instead: <strong>Integrations</strong> page →  <strong>HiBob</strong> tile → <strong>Connect</strong> (see </p><p>Installation steps)</p> |

### &#x20;Support&#x20;

•  Product documentation: docs.docontrol.io&#x20;

•  In-app: use the help/chat widget from any DoControl page&#x20;

• Email: <support@docontrol.io>&#x20;

This guide covers the HiBob HRIS integration only. For other DoControl integrations, see the Integrations section of docs.docontrol.io.&#x20;

\ <br>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.docontrol.io/docontrol-user-guide/integrations/hris/hibob.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.