Integration with BambooHR

Modified on Thu, 3 Jul at 11:09 AM

Integration with BambooHR

Crystal Payroll supports a comprehensive level of integration with BambooHR, a global HR management software used by over 30,000 companies of all sizes. This integration allows you to retrieve employee information, send leave balances, and update pay rates with just a click.

Setting Up BambooHR

First, make sure you have purchased the Advantage package of BambooHR, as the Essentials package does not include Open API support, which is required for the integration with Crystal Payroll. You can view their packages here: BambooHR plans and pricing.

Click "Add New Key".

Enter any name for the "API Key Name", such as "Crystal Payroll".

Click "Generate Key".

Click "Copy Key" and save it somewhere secure. If forgotten, you can repeat the process.

Click "Done".

Now, check that the "Time Off" categories match exactly with those in Crystal Payroll. The names must match exactly — no extra spaces, different characters, or mismatched units.

The following leave categories should be named as follows:

"Annual Leave" for annual leave, measured in hours. By default, this may be named "Vacation Leave", so you will need to rename it or create a new one.

"Sick Leave" for sick leave, measured in days.

"Alternative Leave" for alternative leave, measured in days.

The easiest way to manage these in BambooHR is to configure them all as "Manual Policy" so that accrual is handled by Crystal Payroll.

The final step must be completed Tuesday to Saturday before 12:00 p.m. NZT. This is because it requires assistance from BambooHR support, based in the USA. If attempted outside of these times, the option will not be available.

Click the "Question Mark" icon at the top-right corner of the BambooHR screen.

Select "Chat with us now".

Do not attempt to create the fields yourself, they require specific background IDs.

When the chat box opens, and a support representative is available, copy and paste the message below exactly as is. Do not alter the text, or the integration may not work:

Dear BambooHR,

I am setting up an integration with my payroll system and have been provided the following letter for you.

Please add the following tab and fields under the "People" dashboard:

New custom tab: "Payroll | CP".

New custom text field: "IRD Number (000-000-000) | CP", background ID: customIRDNumberCP

New custom text field: "Tax Code (X or X XX or XX XX) | CP", background ID: customTaxCodeCP

New custom text field: "Withholding Tax Rate (%) (Optional) | CP", background ID: customWithholdingTaxRateCP

New custom text field: "Bank Account Number (00-0000-0000000-00) | CP", background ID: customBankAccountNumberCP

New custom text field: "Default Hours (M-T-W-T-F-S-S) | CP", background ID: customDefaultHoursCP

New custom text field: "KiwiSaver Employee Contribution (%) | CP", background ID: customKiwiSaverEmployeeContributionCP

New custom text field: "KiwiSaver Employer Contribution (%) | CP", background ID: customKiwiSaverEmployerContributionCP

New custom text field: "KiwiSaver ESCT Rate (%) | CP", background ID: customKiwiSaverESCTRateCP

New custom text field: "Casual Employee (Y or N) | CP", background ID: customCasualEmployeeCP

New custom text field: "Region for Anniversary Day (Optional) | CP", background ID: customRegionforAnniversaryDayCP

All fields must be optional, use text field type, and include all brackets and symbols as shown.

Warm regards

Once the representative completes the setup, you’ll see a new tab and fields under each employee’s profile:

Setting Up Crystal Payroll

Go to "Company Settings", then "Import/Export". Under "API Settings", select "BambooHR" from the "HR System" dropdown, then click "Save".

Enter your "Client ID". This is usually the first part of your BambooHR domain name. If unsure, check the address bar on your BambooHR login page — everything before ".bamboohr.com" is your client ID.

Now enter your "API Key", which you should have saved earlier.

Click "Save".

Using the Integration

From "Employee Settings", then "Employee Details", click "BambooHR" at the top-right corner of the page.

You will see three options:

Import new employees from BambooHR

Update an employee’s pay rate from BambooHR

Update an employee’s details from BambooHR

All information, except for leave balances, is pulled from BambooHR. This means you can manage employee records in BambooHR and sync them to Crystal Payroll as needed.

Leave balances work in reverse. When leave is taken or entitlements are updated, you can push the changes to BambooHR by clicking "Step 2: Update Leave Balances" in the top-right.

As shown, the BambooHR integration is simple and efficient. It will save time and eliminate double entry, making your HR processes more streamlined. We hope you found this guide helpful.