Bamboozled: PowerShell and the BambooHR API
15 May 2019
BambooHR is a popular HRIS used globally by small and medium businesses for managing HR and Payroll systems.
For IT professionals, BambooHR’s API offers significant opportunities for automating aspects of day to day operations. For example, using BambooHR’s API to gather staff information, you could:
- Update user information in Active Directory
- Automate the population of Office 365 Groups or distribution lists
- Perform staff onboarding and offboarding tasks automatically
- Populate a staff directory with contact information
These are just a few examples of the kinds of activities you could perform once you’ve hooked into the API. But where do you begin? I’ve written a helper module in PowerShell called Bamboozled that performs the legwork for you.
Check out Bamboozled on Github
How to install Bamboozled
- To begin using Bamboozled, download and extract the module from the link here.
- Save the extracted folder and the Bamboozled.psm1 file to Powershell’s module path. See Microsoft’s documentation for more information.
- That’s all!
Getting started with Bamboozled
Once you’ve installed Bamboozled, you can use Get-BambooHRDirectory in any script you might need it in. For basic operation, you’re going to need two things: an API key with the correct permissions, and the subdomain of your BambooHR tenant.
For the examples below, we’ll assume the API key is ‘abcde’ and the subdomain is ‘xyz’.
To get a directory of users from BambooHR within your PowerShell scripts, use the code below. This will return an array of user objects, each with the module’s default set of user fields. These default fields are id, firstName, lastName, workEmail, and status.
Get-BambooHRDirectory -ApiKey "abcde" -subDomain "xyz"
Return custom fields
If you need more information in BambooHR’s API response, you can use the ‘fields’ parameter to request additional fields, separated by commas. For a full list of available fields, check out the API documentation.
Get-BambooHRDirectory -ApiKey "abcde" -subDomain "xyz" -fields "firstName,lastName,workEmail,supervisorEid"
Return active users only
By default, the PowerShell module will return all BambooHR users, whether or not they’re active users. To limit the results to active employees, you can use the active switch.
Get-BambooHRDirectory -ApiKey "abcde" -subDomain "xyz" -active
Filtering by “Changed since”
If you’d like to output only results from BambooHR that have been changed since a given date, you can use the “since” flag, as below. The date provided must be in ISO 8601 format.
Get-BambooHRDirectory -ApiKey "abcde" -subDomain "xyz" -since "2018-10-22T15:00:00Z"
This post was last updated on 8 October 2019