HiBob
HiBob Integration Workflow Guide
Overview
This guide covers best practices for running HiBob as your HRIS with ChartHop. HiBob serves as the source of truth for employee records, organizational structure, and compensation. Understanding how the sync works is critical to avoiding incorrect headcount, org chart issues, and data mapping problems.
How the Integration Works
What Data Syncs from HiBob
- People: Name, email, image, birth date, gender, ethnicity
- Jobs: Title, department, location, manager, start date, employment type
- Compensation: Base salary, pay period, currency, variable compensation
- Change History: Work changes, employment changes, salary changes, lifecycle events (hires and departures)
How Matching Works
The sync uses the HiBob employee ID (hibobid) as the unique identifier for matching records between systems. Each sync cycle fetches current worker data and historical changes, exports them to CSV, and imports them into ChartHop with upsert enabled.
Sync Modes
- Initial sync: Pulls all workers and full change history. Automatically detects the head of the organization and builds the org chart from scratch.
- Incremental sync: Pulls changes from a configurable lookback window (default: 30 days) plus all current worker data to keep records up to date.
Lifecycle Status Handling
HiBob lifecycle statuses map to ChartHop as follows:
- "employed" → Creates a HIRE change in ChartHop
- "hired" (offer accepted, not yet started) → Ignored — does not create a HIRE change
- "terminated" → Creates a DEPART change with reason type (voluntary/involuntary) and regret tracking
Employment Type Mapping
HiBob's employment.type field is mapped to ChartHop's employment type as follows:
HiBob employment.type | HiBob employment.contract | ChartHop Employment Type |
|---|---|---|
Starts with "Perm" (e.g., "Permanent", "Permanent (UK)") | "Full time" | FULL |
Starts with "Perm" | "Part time" | PART |
Starts with "Contract" (e.g., "Contract", "Contractor") | Any | CONTRACT |
Starts with "Fixed" (e.g., "Fixed-term") | Any | TEMP |
"Apprentice" or "Intern" | Any | INTERN |
Any other value | Any | Passed through unmapped |
⚠️ Important: If your organization uses non-standard employment type values for contractors (e.g., "Independent Contractor", "Consultant", "External", "Contingent Worker"), these will not be recognized as CONTRACT type. They will pass through unmapped and may be treated as standard employees in headcount calculations.
Action required: Ensure all contractor employment types in HiBob begin with "Contract" or "Fixed". If this is not possible, contact support to discuss custom mapping options.
Excluding Employment Types from Sync
If certain employment types should not sync to ChartHop at all, use the excludeEmployment app option. For example, setting excludeEmployment: ["Intern", "Apprentice"] will skip those workers entirely during sync.
Initial Setup Checklist
Understand the daysBack setting. The default is 30 days. This setting only applies to incremental syncs — it controls how far back the sync looks for changes. Initial sync is not affected and pulls all available history. If you need an incremental sync to pick up historical changes older than 30 days (e.g., a missed hire event or a retroactive correction in HiBob), temporarily increase this value before running the sync.
Enable logUnmappedFields during initial setup to identify HiBob custom fields that need mapping.
Verify employment type values in HiBob match the expected patterns (see Employment Type Mapping above).
Verify all custom field mappings point to the correct HiBob fields before running the first sync.
Review the org chart after initial sync to identify any orphaned employees (missing manager or missing hire change).
Confirm that any department or location filters applied to the sync do not exclude managers of employees who are included in the sync.
Common Issues and Troubleshooting
Employee Not Appearing in Org Chart
Symptom: An employee exists in HiBob but doesn't appear in ChartHop's org chart.
Common causes:
- Missing manager: The org chart is built from manager relationships. If the employee's manager field in HiBob is empty or references an unknown ID, the employee will exist in ChartHop but won't be connected to the org tree.
- Missing HIRE change: ChartHop requires a HIRE change to place a person into a job. HiBob's lifecycle status must be "employed" — a status of "hired" (offer accepted but not started) is intentionally excluded from sync. Verify the employee's lifecycle status in HiBob.
- Manager in excluded department: If you're using sync filters to exclude certain departments, any employee whose manager is in an excluded department will have an incorrect or missing manager assignment. The sync cannot look up managers that don't exist in ChartHop.
- HIRE event missing manager data: If HiBob's lifecycle/work history doesn't include a manager on the hire date, ChartHop may fail to create the hire. Check if the employee's earliest work history entry includes a reportsTo value.
- Hire date older than history lookback: If the employee's hire date was missed during initial sync and the daysBack lookback window on subsequent incremental syncs doesn't reach back far enough, their HIRE change will not be imported. Temporarily increase daysBack and run a sync, or contact support.
- Future start date: Employees with a future start date appear as "starting" (is:starting) and may be excluded from default org chart views. They will appear once their start date arrives.
Diagnostic steps:
- Search for the person in ChartHop by name or email
- Check if they have a HIRE change with a valid date
- Check if their job has a manager relationship
- Search for duplicate person records
- Verify the employee's lifecycle status and manager in HiBob
Contractors Consuming Permanent Headcount
Symptom: A contractor synced from HiBob is placed into an open permanent role, consuming planned headcount in the wrong department.
Cause: When HiBob syncs a new hire, ChartHop's matching logic looks for an open job with the same title and manager. This matching does not currently distinguish between permanent and contractor roles. If a contractor has the same title as an open permanent requisition, they may be placed into that slot.
Current workarounds:
- Use distinct job titles for contractors vs. permanent roles (e.g., "Software Engineer - Contractor" vs. "Software Engineer")
- Use the excludeEmployment option to exclude contractors from the HiBob sync entirely, and manage contractor records manually in ChartHop
- After sync, review contractor placements and manually move any that were incorrectly assigned
Custom Field Mapping Issues
Symptom: A HiBob custom field is not appearing in ChartHop, or is mapped to the wrong ChartHop field.
Cause: HiBob custom fields are only synced if they are explicitly included in the field mapper configuration. Unmapped fields are discarded during sync.
Troubleshooting:
- Enable the logUnmappedFields app option to see which HiBob fields are available but not mapped
- Verify that the field mapper points to the correct HiBob field path — HiBob uses a lookup table system where field values can be keys into "lists", and the displayed value may differ from the API value
- If a ChartHop field is mapped to the wrong HiBob column (e.g., "Team" mapped to a column that returns "Team Type" values), update the field mapper to reference the correct source field
Custom Group Fields Appending Instead of Overwriting
Symptom: An employee shows multiple values for a custom group field (e.g., multiple locations or sub-teams) after each sync, rather than having the old value replaced.
Cause: Custom group fields in ChartHop currently append new values by default. Single-value overwrite mode for custom groups is not yet supported.
Incorrect Manager After Department Filter Exclusion
Symptom: An employee shows the wrong manager (often the head of the organization) after sync.
Cause: A sync filter is excluding the department that contains the employee's actual manager. When ChartHop can't find the referenced manager in the synced data, it falls back to assigning the head job as the manager.
Resolution: Either include the manager's department in the sync filter, or manually maintain the manager relationship for affected employees. Note that all employees managed by someone in the excluded department will be affected, not just one.
Preferred Name Not Syncing
Symptom: An employee's preferred name in HiBob is not reflected in ChartHop.
Cause: The default field mapper maps employee.firstName and employee.surname to ChartHop's name fields. HiBob preferred name fields may not be included in the default mapping.
Resolution: Verify that the preferred name field from HiBob is mapped to ChartHop's name.pref field in the field mapper configuration. If not present, add the mapping.
Default Field Mappings
The following fields are mapped by default from HiBob to ChartHop:
ChartHop Field | HiBob Source (Current State) | HiBob Source (Change History) |
|---|---|---|
First Name | employee.firstName | — |
Last Name | employee.surname | — |
Work Email | employee.email | — |
Title | employee.work.title | work.title |
Manager | employee.work.manager | work.reportsTo.id |
Department | employee.work.department | work.department |
Location | employee.work.site | work.site |
Start Date | employee.work.startDate | — |
Employment Type | employment.type + employment.contract | employment.type + employment.contract |
Base Compensation | Salary amount + pay period + currency | Salary history |
Variable Compensation | Variable type + amount + currency | Variable history |
Lifecycle Events | — | lifecycle.status (employed/terminated) |
Any HiBob field not listed above requires explicit addition to the field mapper configuration.
Best Practices
- HiBob is the source of truth for employee data. Configure it as the primary sync and let it maintain all records.
- Standardize employment types in HiBob. Contractors must use values starting with "Contract" or "Fixed" to be correctly classified.
- Avoid excluding departments from sync if those departments contain managers of included employees.
- Verify custom field mappings during setup using logUnmappedFields.
- Use distinct titles for contractor vs. permanent roles to prevent incorrect job matching.
- Monitor the first few sync cycles after setup — check for orphaned employees, incorrect managers, and unexpected headcount assignments.
- Verify lifecycle statuses in HiBob — only "employed" creates a HIRE in ChartHop. Employees with "hired" status will not sync until their status changes.