All Collections
Stakeholders
HRIS integrations
How do I connect my Hibob account?
How do I connect my Hibob account?

This guide will outline the steps needed to set up a Service User, link it with Ledgy and configure the sync between the two platforms.

Support Team avatar
Written by Support Team
Updated over a week ago

What is your integration use case?


Use case 1: I have not created any stakeholder profiles in my Ledgy account.

1. Connect HiBob with Ledgy

First, go to Company Settings > Data Management > HR system integration > Connect.

Scenario 1: Existing connection

If you’re already connected — there is nothing to do! Feel free to jump to ‘Configure your HRIS field import into Ledgy

If you are connected, but wish to adjust your API key permissions or change HRIS provider, please ‘disconnect’ and follow the new connection instructions, or reach out to customer support.

Scenario 2: Establishing a new connection / no existing connection

1.1 Select HiBob from the HR system logo picker and click the Connect button


Choose the recommended authentication method via Service User ID and Token.

There is also an option to authenticate via API key, but this method will be deprecated in Q1 2024, that's why it's recommended to use the Service User ID and Token authentication method.

1.2 Create a Service User and link it with a dedicated Permission Group in your HiBob Account

1.2.1 Create a Service User

1) In your settings, go to integrations and click Manage Service Users

2) Create a new Service User and save the Service User ID and Token


1.2.2 Create a Permission Group

3) Back in your settings, go to Permission Groups and select Create Group.

4) Name the group, then, in the Group members section, choose Select people by condition and select Select people.

5) In the Select people by condition pop-up, delete the existing condition and add the Service User previously created in the dropdown menu for Add Specific Employees then click Apply.

Attention! Please ensure that you add only the service user because it will define who has access to this permission group!

6) Finish the initial creation of the Group by selecting Create. If a pop-up appears, Confirm the creation of the group.

7) Under People's Data, edit the data that can be accessed by choosing Select people by condition and selecting Edit.

a.) Click Select by Condition

b.) Click Edit

c.) Lifecycle Status = Employed, Hired, Terminated

8) Under People's Data add the following permissions.

Please note the permissions listed below are the minimal required permissions for the reading capability of the employee fields in HiBob so that we can map the default fields in Ledgy.

Fields mapped by default (Simple)

  • Identifier

  • Name

  • Email (i.e work email)

  • Personal Email

  • Address Line 1

  • Address Line 2

  • ZIP Code

  • City

  • Country

  • Birthdate

  • Group Name

  • Start Date (not visible on stakeholder modal)

  • Termination Date (not visible on stakeholder modal)

  • Employment Status (not visible on stakeholder modal)

  • Pay Rate (not visible on stakeholder modal)

  • Pay Period (not visible on stakeholder modal)

  • Pay Currency (not visible on stakeholder modal)

  • Employment Type (not visible on stakeholder modal)

  • Team (not visible on stakeholder modal)

If you don't want to share specific data points with Ledgy, you do not need to include those!

People:

  • Address

    • View selected employees' Address sections

    • View selected employees' Address section histories

  • Employment

    • View selected employees' Employment sections

    • View selected employees' Employment section histories

  • History

    • View selected employees' profile changes history

  • Identification (required)

    • View selected employees' Identification sections

    • View selected employees' Identification section histories

  • Lifecycle

    • View selected employees' Lifecycle sections (This is needed to surface Employment Status)

    • View selected employees' Lifecycle section histories

  • Payroll

    • View selected employees' Payroll sections

    • View selected employees' Payroll section histories

  • Personal (required)

    • View selected employees' Personal sections

    • View selected employees' Personal section histories

    • Edit selected employee's Personal sections (Note: This is needed to surface Date of Birth. Merge will NOT edit any employee sections)

  • Personal Contact Details

    • View selected employees' Personal contact details sections

    • View selected employees' Personal contact details section histories

  • Work

    • View selected employees' Work section histories

  • Work Contact Details

    • View selected employees' Work Contact Details section histories

Note: If you want to map custom fields with Ledgy, please enable the viewing permission of the group where the custom field is included!

For example, map custom Equity-related information with your Ledgy account.

9) Click Apply and Save.


1.3 Obtaining an API key from HiBob (not recommended)

We will be deprecating the Hibob API Key authentication method at the end of Q1 2024. We recommend to use the Service User ID authentication method

1) Log in and click on your avatar in the upper right. Select API Access in the menu.

2) Leave the default approved scopes as shown below. Copy the token and add it to Merge Link.

For minimum permissions, include:

  • Full employee read

  • Employee fields read

  • Payroll info read


1.4 Link your HiBob account with Ledgy

Sign in using your HiBob Service User ID and HiBob Token, and hit the Submit button.

You’ll be given the option to map additional HR field mappings from your HRIS into Ledgy. Hit ‘Skip for now’ and request additional field mappings via the in-app chat, once linking is complete.


2. Configure your HRIS field import into Ledgy

You need to configure the fields before initiating sync. Hit ‘Configure’ to open up the modal below. You are able to change the configuration later and at any future point.

Nb. please close & re-open the modal to first load the configure screen. Loading may take up to 5 minutes.

2.1. Stakeholder identifier should be a unique identifier and the value should exist for all employees in HRIS. In HiBob's case, the identifier can be “Work email” or "Employee number”.

  • If you already have stakeholders in Ledgy, please see FAQ below.

2.2. Stakeholder email: Choose which employee field to map to Ledgy’s primary email.

2.3. Additional fields to import allow you to optionally import any of the following fields:

  • Manager

  • Mobile Phone Number

  • Pay Rate

2.4. Hover over the “❓ Some basic stakeholder fields” to see the default fields mapped from HRIS into Ledgy

2.5. If there are additional fields you wish to map to Ledgy from your HRIS, please click the link to reach out to support and request new HR field mappings via chat.

2.6. You can add "Sync if" conditions to specify which employees to sync in Ledgy.

⚠️ Note: filters are additive, meaning that stakeholders must match all conditions for a rule to apply to them. You can use ‘OR’ conditions to select multiple values for a given filter. For example: you may want to sync employees across multiple countries, and of multiple groups.


3. Syncing stakeholders into Ledgy

Once you have setup the configuration, you can sync stakeholders. Hit ‘sync’ to preview stakeholders that will be created or updated in Ledgy.

Nb. ‘Mobile number’ will appear as invalid if the country code is not inputted in HRIS. Please add country code to HRIS entries to successfully sync mobile number - otherwise, this will need to be manually updated in Ledgy.


Use case 2: I have already created stakeholder profiles in my Ledgy account.

1. Connect HiBob with Ledgy

First, go to Company Settings > Data Management > HR system integration > Connect.

Scenario 1: Existing connection

If you’re already connected — there is nothing to do! Feel free to jump to ‘Configure your HRIS field import into Ledgy

If you are connected, but wish to adjust your API key permissions or change HRIS provider, please ‘disconnect’ and follow the new connection instructions, or reach out to customer support.

Scenario 2: Establishing a new connection / no existing connection

1.1 Select HiBob from the HR system logo picker and click the Connect button


Choose the recommended authentication method via Service User ID and Token.

There is also an option to authenticate via API key, but this method will be deprecated in Q1 2024, that's why it's recommended to use the Service User ID and Token authentication method.

1.2 Create a Service User and link it with a dedicated Permission Group in your HiBob Account

1.2.1 Create a Service User

1) In your settings, go to integrations and click Manage Service Users

2) Create a new Service User and save the Service User ID and Token


1.2.2 Create a Permission Group

3) Back in your settings, go to Permission Groups and select Create Group.

4) Name the group, then, in the Group members section, choose Select people by condition and select Edit.

5) In the Select people by condition pop-up, delete the existing condition and add the Service User previously created in the dropdown menu for Add Specific Employees then click Apply.

Attention! Please ensure that you add only the service user because it will define who has access to this permission group!

6) Finish the initial creation of the Group by selecting Create. If a pop-up appears, Confirm the creation of the group.

7) Under People's Data, edit the data that can be accessed by choosing Select people by condition and selecting Edit.

a.) Click Select by Condition

b.) Click Edit

c.) Lifecycle Status = Employed, Hired, Terminated

8) Under People's Data add the following permissions.

Please note the permissions listed below are the minimal required permissions for the reading capability of the employee fields in HiBob so that we can map the default fields in Ledgy.

Fields mapped by default (Simple)

  • Identifier

  • Name

  • Email (i.e work email)

  • Personal Email

  • Address Line 1

  • Address Line 2

  • ZIP Code

  • City

  • Country

  • Birthdate

  • Group Name

  • Start Date (not visible on stakeholder modal)

  • Termination Date (not visible on stakeholder modal)

  • Employment Status (not visible on stakeholder modal)

  • Pay Rate (not visible on stakeholder modal)

  • Pay Period (not visible on stakeholder modal)

  • Pay Currency (not visible on stakeholder modal)

  • Employment Type (not visible on stakeholder modal)

  • Team (not visible on stakeholder modal)

If you don't want to share specific data points with Ledgy, you do not need to include those!

People:

  • Address

    • View selected employees' Address sections

    • View selected employees' Address section histories

  • Employment

    • View selected employees' Employment sections

    • View selected employees' Employment section histories

  • History

    • View selected employees' profile changes history

  • Identification (required)

    • View selected employees' Identification sections

    • View selected employees' Identification section histories

  • Lifecycle

    • View selected employees' Lifecycle sections (This is needed to surface Employment Status)

    • View selected employees' Lifecycle section histories

  • Payroll

    • View selected employees' Payroll sections

    • View selected employees' Payroll section histories

  • Personal (required)

    • View selected employees' Personal sections

    • View selected employees' Personal section histories

    • Edit selected employee's Personal sections (Note: This is needed to surface Date of Birth. Merge will NOT edit any employee sections)

  • Personal Contact Details

    • View selected employees' Personal contact details sections

    • View selected employees' Personal contact details section histories

  • Work

    • View selected employees' Work section histories

  • Work Contact Details

    • View selected employees' Work Contact Details section histories

Note: If you want to map custom fields with Ledgy, please enable the viewing permission of the group where the custom field is included!

For example, map custom Equity-related information with your Ledgy account.

9) Click Apply and Save.


1.3 Obtaining an API key from HiBob (not recommended)

We will be deprecating the Hibob API Key authentication method at the end of Q1 2024. We recommend to use the Service User ID authentication method

1) Log in and click on your avatar in the upper right. Select API Access in the menu.

2) Leave the default approved scopes as shown below. Copy the token and add it to Merge Link.

Minimum permissions include:

  • Full employee read

  • Employee fields read

  • Payroll info read


1.4 Link your HiBob account with Ledgy

Sign in using your HiBob Service User ID and HiBob Token, and hit the Submit button.

You’ll be given the option to map additional HR field mappings from your HRIS into Ledgy. Hit ‘Skip for now’ and request additional field mappings via the in-app chat, once linking is complete.


2. Configure your HRIS field import into Ledgy

You need to configure the fields before initiating sync. Hit ‘Configure’ to open up the modal below. You are able to change the configuration later and at any future point.

Nb. please close & re-open the modal to first load the configure screen. Loading may take up to 5 minutes.

2.1. Stakeholder identifier should be a unique identifier and the value should exist for all employees in HRIS. In HiBob's case, the identifier can be “Work email” or "Employee number”.

2.2. Stakeholder email: Choose which employee field to map to Ledgy’s primary email.

2.3. Additional fields to import allow you to optionally import any of the following fields:

  • Manager

  • Mobile Phone Number

  • Pay Rate

2.4. Hover over the “❓ Some basic stakeholder fields” to see the default fields mapped from HRIS into Ledgy

2.5. If there are additional fields you wish to map to Ledgy from your HRIS, please click the link to reach out to support and request new HR field mappings via chat.

2.6. You can add "Sync if" conditions to specify which employees to sync in Ledgy.

⚠️ Note: filters are additive, meaning that stakeholders must match all conditions for a rule to apply to them. You can use ‘OR’ conditions to select multiple values for a given filter. For example: you may want to sync employees across multiple countries, and of multiple groups.

2.7. Update your stakeholders:

  1. To edit your stakeholder in bulk, go to Stakeholders > click the "Bulk" button

  2. Select "Natural person" > Click on the "Stakeholders" button to download your stakeholder list

  3. Add the unique identifier (Employee ID or Work email) for each stakeholder from your HRIS Platform in the Identifier column in the Excel file

  4. Upload the Excel file back to your account


3. Syncing stakeholders into Ledgy

Once you have setup the configuration, you can sync stakeholders. Hit ‘sync’ to preview stakeholders that will be created or updated in Ledgy.

Nb. ‘Mobile number’ will appear as invalid if the country code is not inputted in HRIS. Please add country code to HRIS entries to successfully sync mobile number - otherwise, this will need to be manually updated in Ledgy.


FAQ

Which HRIS fields are mapped into Ledgy?

By default, we now map more data from your HRIS into Ledgy, and you can select from optional fields to also map into Ledgy.

Fields mapped by default (Simple)

  • Identifier

  • Name

  • Email (i.e work email)

  • Personal Email

  • Address Line 1

  • Address Line 2

  • ZIP Code

  • City

  • Country

  • Birthdate

  • Group Name

  • Start Date (not visible on stakeholder modal)

  • Termination Date (not visible on stakeholder modal)

  • Employment Status (not visible on stakeholder modal)

  • Pay Rate (not visible on stakeholder modal)

  • Pay Period (not visible on stakeholder modal)

  • Pay Currency (not visible on stakeholder modal)

  • Employment Type (not visible on stakeholder modal)

  • Team (not visible on stakeholder modal)

Nb. Depending on the Service User's permissions, some default fields will not be mapped.

For fields that are not supported by default by your HRIS, please follow FAQ for How do I setup HR field mappings from my HRIS into Ledgy?”, to request the field mapping via support chat. You can then map the field mapping into a Ledgy custom field.


Why can I only see partial data for my synced stakeholders?

Oh no! Possible reason:

  • The Service User or API key that is used for authentication has permission restrictions.

If this issue cannot be resolved by changing the Service User or API key permission or by adding the missing field via a custom field (see FAQ for How do I setup HR field mappings from my HRIS into Ledgy?) - you can manually input field value in Ledgy for a Stakeholder, or via bulk excel.


How do I setup HR field mappings from my HRIS into Ledgy?

Customer support via in-app chat - after linking flow

Simply skip the step in the linking process, and reach out to support via the in-app chat bubble to request more HR field mappings. Once added, you will see the HR field mapping appear in the configure screen - ready to be mapped to the Ledgy custom fields created.

HRIS Fields Not Accepted by Ledgy

• Racial or ethnic origin

• Political affiliation

• Religious affiliation (including tax elections)

• Trade union membership

• Genetic or health data (including medical records)

• Biometric data

• Data on sex activity or sexual orientation (does not include gender)

• Criminal records or background check information

• Banking or payment information (including credit card, IBAN)

• Credit rating

• License or passport numbers

• US social security number

For data protection reasons, we want to avoid storing this information in Ledgy. But if you need the information in your Ledgy account, we can make an exception. Please reach out to [email protected] and explain your reasons.


What are Ledgy custom fields?

Ledgy stakeholder custom fields are company-wide fields that you create in Ledgy. They exist on each stakeholder. Now, you can create your own HR field mappings (see above) and sync them into Ledgy custom fields.

They can be used as variables for document templating and in reports, as grid columns, and as “group by” options for your stakeholders in Ledgy, and more.


What if I already have stakeholders in Ledgy, and now want to sync with HRIS?

Ledgy requires a Stakeholder identifier to match existing stakeholders in Ledgy with employees in HRIS. If no identifiers exist in Ledgy and the names do not match 100% between your HRIS platform and Ledgy, then duplicates may be created in Ledgy in the syncing process.

If you have created your stakeholders without your HRIS platform in your Ledgy account and now wish to connect your HRIS platform, please follow the steps to ensure that the sync doesn't create duplicate stakeholders.

Update your stakeholders:

  1. To edit your stakeholder in bulk, go to Stakeholders > click the "Bulk" button

  2. Select "Natural person" > Click on the "Stakeholders" button to download your stakeholder list

  3. Add the unique identifier (Employee ID or Work email) for each stakeholder from your HRIS Platform in the Identifier column in the Excel file

  4. Upload the Excel file back to your account

Correct mapping:

  1. Follow the step 1 and step 2 in the integration process

  2. Go to Company Settings > Data Management > HR System Integration > Click the "Configure" button

  3. Map the name of the identifier that you added in the Excel file with the Ledgy field "Stakeholder identifier"

  4. Click the "Save" button to save the mapping

Now you can sync Ledgy with your HRIS platform, and we will not create any duplicates!


Can I still use this page without connecting my HRIS?

You can still use the Data Management page to manage your stakeholder’s custom fields.


What happens when an employee is terminated on the HRIS?

When syncing Ledgy with your HRIS, terminated employees are not automatically recognised as terminated by Ledgy. Thus, if not specified otherwise, Ledgy will prompt you to create or update them.

There are different options for managing the terminated employees:

  • Add a "Sync if" condition such as sync if "status" = "active" → this will exclude the inactive/terminated employees from the sync. However, this will not automatically delete the terminated stakeholders from Ledgy if they had already been previously created (learn more about deleting stakeholders or revoking portfolio access)

  • Sync the terminated employees to Ledgy, and assign them to a stakeholder group such as "Ex-employee" or "Alumni"

  • Delete the terminated employees from your HR management platform → this will prevent the terminated stakeholders from being created or synced in the future. However, this will not automatically delete the stakeholders from Ledgy if they had already been previously created (learn more about deleting stakeholders or revoking portfolio access

Did this answer your question?