Sync people from BambooHR
Connect BambooHR with an API key and Polzy keeps your members up to date on a schedule — and within moments of a change if you add a BambooHR webhook.
On this page
Connect BambooHR and Polzy reads your employee directory on a schedule. New hires arrive as members of your workspace, changes to their job title, department or manager follow at the next sync, and people who leave stop receiving surveys. Add a BambooHR webhook as well and a change reaches Polzy within moments instead of at the next sync.
People sync is on Team and up, and only workspace admins can connect a source. Polzy only reads from BambooHR: it never writes back or changes an employee record.
Before you start
You need:
- To be an admin of the Polzy workspace, on Team or higher, with People sync switched on under Settings → General → What this workspace does.
- A BambooHR user who may create API keys and can see every employee and field Polzy should read — including past employees, termination dates and supervisors. An API key sees exactly what its user sees.
- Your BambooHR subdomain: the part of your BambooHR address before
.bamboohr.com. Forhttps://acme.bamboohr.comit isacme. - For webhooks: a BambooHR admin, and the Integrations page in Polzy, which comes with Business.
A workspace syncs from one source at a time. If another source is connected, disconnect it first. If your organization provisions people through SCIM, a people source cannot be connected at all — see SCIM.
Create an API key in BambooHR
- Sign in to BambooHR as the user whose access the key should have. A dedicated user for integrations is a good idea: if that user is deactivated, the key stops working.
- Click your name in the lower-left corner and choose API Keys.
- Add a new key, name it Polzy, and generate it.
- Copy the key straight away. BambooHR shows it only once.
See BambooHR: Getting started with the API.
Connect BambooHR in Polzy
- Open Contacts → Sync & fields.
- Under Available sources, find BambooHR and choose Connect. A panel opens with three steps: Connection, Sync settings and Field mapping.
- Enter your BambooHR Subdomain and paste the API Key. Leave Webhook secret empty for now; it is for the webhook below.
- Choose Test connection. Successfully connected to BambooHR. Found N employees. means the key works.
- Choose Next, check the sync settings (see below), and choose Next again.
- On Field mapping, keep the default mapping or switch on Custom field mapping (see below), then choose Connect.
The key is stored encrypted and is only used to read from BambooHR. Polzy checks it again when you choose Connect: if BambooHR refuses it, nothing is saved.
Sync settings
| Setting | What it does | Default |
|---|---|---|
| Sync Frequency | How often Polzy reads BambooHR: every 30 minutes, every hour, every 4 hours or daily. | Every hour |
| Disable Terminated Employees | Someone Polzy brought in from BambooHR who no longer appears there is deactivated at the next sync. | On |
| Send Invitation Emails | New members with an email address get an invitation to sign in to Polzy. | On |
| Default Role | The role new members get: Viewer, Editor or Admin. It applies only to people the sync creates. | Viewer |
| Save Raw Data | Keeps a copy of each record as BambooHR sent it beside the person in Polzy. Leave it off unless you are troubleshooting a mapping: it stores more personal data than you need. | Off |
Map the fields
Polzy reads BambooHR through a report of the fields it needs, past employees included. The default mapping fills:
| Polzy field | From BambooHR |
|---|---|
workEmail | |
| First name, last name | firstName, lastName |
| Job title | jobTitle |
| Department, office | department, location |
| Phone number | mobilePhone |
| Employee ID, start date | id, hireDate |
| Active status | worked out from terminationDate and status |
| Manager | supervisorId |
To change it, switch on Custom field mapping. Each row then has a source to choose — other fields on offer include workPhone, employeeNumber and division — and an If empty, use value, written when BambooHR has nothing for that person. A value BambooHR does send is never overwritten.
A few things to know:
- Only your workspace's fields are filled. Department or office are kept only if your workspace has a field with that name. Add one with Add field on Sync & fields, then map it.
- Groups. To compare results by a field, make it a List field and switch on Groups beside it in the Field mapping table. Values from BambooHR are matched to the field's options.
- Real examples. Once connected, choose Settings on Sync & fields and open Field mapping again: the list then comes from five real records, each with an Example.
- Managers. The supervisor becomes the person's manager when the supervisor is in Polzy too. If they are not there yet, the link is made at a later sync. Managers need Reporting lines switched on in the workspace.
Preview and run the first sync
- On Sync & fields, choose Preview a sync under Sync history. Polzy works out what a sync would add, update and deactivate, without changing anything, and opens the log where the result appears as Preview.
- Check the preview. If names, emails or departments look wrong, fix the mapping under Settings and preview again.
- Choose Sync Now. The result appears in Sync history.
People are matched by their BambooHR ID, and then by email address, so someone you had already invited by hand is updated rather than added twice.
Get changes within moments with a webhook
Without a webhook, changes arrive at the next scheduled sync. With one, BambooHR tells Polzy which employees changed and Polzy reads each of them straight away.
- In Polzy, open Integrations, then BambooHR, and copy the address under Receiving. It is made for your connection and ends in
/bamboohr. - In BambooHR, open Account Settings and choose Webhooks. If it is missing, BambooHR support can switch webhooks on for your account.
- Add a webhook named Polzy, paste the address as its URL, and choose JSON as the format.
- Choose the fields to monitor — the ones you map in Polzy, such as name, work email, job title, department, location, status and supervisor.
- Generate the private key and copy it before you save. BambooHR shows it only once.
- In Polzy, open Contacts → Sync & fields, choose Settings, paste the private key into Webhook secret, and choose Save on the last step.
BambooHR signs each call with the private key (X-BambooHR-Signature and X-BambooHR-Timestamp). Polzy refuses a call that is unsigned, signed with another key or more than five minutes old, and does nothing twice when the same call arrives again. Each change appears in Full log as a run of its own, marked Webhook. See BambooHR: Webhooks.
Schedule and sync history
After the first sync Polzy runs on its own, at the frequency you chose, give or take a few minutes. The line under BambooHR's name shows when it last synced, how often it runs, and how many people and groups it brought in. Sync history lists the last five runs — Success, Partial (some people were skipped or failed), Failed or Preview — and Full log opens every run, with each change it made.
If a sync fails, Polzy tries again later, waiting longer each time. After three failures in a row, or straight away when BambooHR refuses the key, the source shows Needs attention and admins are told. Sync Now works again once the source is connected: fix the key under Settings and save.
When someone leaves
- Terminated in BambooHR. Someone with a termination date or the status Terminated is deactivated at the next sync, or at once with a webhook. Deactivated people receive no surveys and use no seat; their past answers stay.
- Gone from BambooHR. With Disable Terminated Employees on, someone who no longer appears in BambooHR at all is deactivated too.
- Blocked in Polzy. Someone an admin blocked in Polzy stays blocked, whatever BambooHR says.
Nobody is deleted by a sync.
Troubleshooting
| What you see | Why | What to do |
|---|---|---|
| BambooHR refused this API key: … The key needs report access. | The key was revoked, its user was deactivated, or the user may not run reports. | Create a key as a user with report access and paste it under Settings. |
| Failed to fetch from BambooHR | BambooHR could not be reached, or the subdomain is wrong. | Check the subdomain, then choose Sync Now. |
| Everyone shows as active, leavers included | The key's user cannot see termination dates or status. | Give that user access to those fields in BambooHR. |
| Webhook changes never arrive | No Webhook secret is saved, it does not match the private key, or the address is wrong. | Generate a new private key, paste it into Webhook secret, and check the URL in BambooHR. |
| N people were not imported: the plan has no seats left for them. | Every member uses a seat, and the plan is full. | Free seats or change plan, then choose Sync Now. |
| … is already importing people. Disconnect it before connecting another source. | A workspace syncs from one source at a time, and another one is connected. | Open that source's Settings and choose Disconnect first. |
Good to know
- Members, not contacts. Everyone from BambooHR is a member: they can sign in and each uses a seat. A sync that would go over your seats imports the people who fit, stops there and tells admins — see Usage and limits.
- The webhook is optional. Scheduled syncs keep running with or without it, and pick up anything a webhook missed.
- Disconnect or remove. Under Settings, Disconnect stops syncing and keeps the settings and history, so you can reconnect later; Remove deletes the connection. Either way, the people already synced stay in Polzy and are no longer updated.
- Need a hand? The connect panel's Ask Polzy link explains where each value lives in BambooHR.
Useful links
- BambooHR: Getting started with the API — creating an API key and finding your subdomain.
- BambooHR: Webhooks — how BambooHR sends and signs changes.
- People and contacts — fields, groups and members.
Related articles
Signed-in members can ask Polzy or message the team from Support. How fast we reply depends on your plan.