A simple (unofficial) PowerShell module to interact with the BambooHR API. For more information about this module, see the Bamboozled article on my personal blog.

Recommended: From the PowerShell Gallery

1. Open PowerShell (Core or Desktop)
2. Run "install-module -name Bamboozled"
3. Confirm the prompt to install

Manually

1. Download and unzip the module.
2. Copy to PowerShell's modules folder in your environment. See this article for details.
3. That's it!

Available functions

• Get-BambooHRDirectory: Gets a directory of users from BambooHR
• Get-BambooHRUser: Gets a single user from BambooHR
• Get-BambooHRFields: Uses the BambooHR meta API to get a list of all available fields
• Update-BambooHRUser: Takes a hash table of BambooHR fields and values to update a user's information

The basic syntax for the Get-BambooHRDirectory commandlet is below. This commandlet also provides a few options, detailed later.

Get-BambooHRDirectory -ApiKey "xxxxxxxxxxxxxxxxxxxxxxxxxxxx" -subDomain "companyname"

When run, this command will output a list of all employees, past and present, including all fields available from BambooHR's API. For a full list of these fields, see this link.

To filter by active users, use the 'active' flag:

Get-BambooHRDirectory -ApiKey "xxxxxxxxxxxxxxxxxxxxxxxxxxxx" -subDomain "companyname" -active

To adjust the fields returned in the results, you can use the fields flag:

Get-BambooHRDirectory -ApiKey "xxxxxxxxxxxxxxxxxxxxxxxxxxxx" -subDomain "companyname" -fields "firstName,lastName,workEmail,supervisorEid"

A list of available fields can be found in BambooHR's API documentation, or by using the Get-BambooHRFields commandlet. This module expects the field names to be provided as written in BambooHR's documentation, separated by commas (no spaces).

To find a list of user records that have changed since a specified date, you can use the 'since' flag as below. The module expects the time to be provided in ISO 8601 format.

Get-BambooHRDirectory -ApiKey "xxxxxxxxxxxxxxxxxxxxxxxxxxxx" -subDomain "companyname" -since "2018-10-22T15:00:00Z"

The basic syntax for the Get-BambooHRUser commandlet is below. This commandlet also provides a few options, detailed later.

Get-BambooHRUser -ApiKey "xxxxxxxxxxxxxxxxxxxxxxxxxxxx" -subDomain "companyname" -id 300

The above command will output BambooHR's information related to the employee with a unique ID of '300'.

If you don't have the employee's ID, you can use their email address instead. Note however, this performs a full directory lookup first, extracts the user's ID, and then performs an API request for that user's ID. If you have the employee's unique ID, the command above will be considerably quicker.

Get-BambooHRUser -ApiKey "xxxxxxxxxxxxxxxxxxxxxxxxxxxx" -subDomain "companyname" -emailAddress "[email protected]"

To adjust the fields returned in the results, you can use the fields flag:

Get-BambooHRUser -ApiKey "xxxxxxxxxxxxxxxxxxxxxxxxxxxx" -subDomain "companyname" -id 300 -fields "firstName,lastName,workEmail,supervisorEid"

A list of available fields can be found in BambooHR's API documentation, or by using the Get-BambooHRFields commandlet. This module expects the field names to be provided as written in BambooHR's documentation, separated by commas (no spaces).

The basic syntax for the Get-BambooHRFields commandlet is below.

Get-BambooHRFields -ApiKey "xxxxxxxxxxxxxxxxxxxxxxxxxxxx" -subDomain "companyname"

To update a BambooHR user's details, use the command below. If successful, the command returns TRUE.

Update-BambooHRUser -apiKey "xxxxxxxxxxxxxxxxxxxxxxxxxxxx" -subDomain "companyname" -id 300 -fields @{firstName="Simon";lastName="Buckley"}

The -fields parameter accepts a hash table containing the fields and values that you wish to update. A list of available fields can be found in BambooHR's API documentation, or by using the Get-BambooHRFields commandlet. To make the script more manageable, you can pass a variable to the parameter like below:

$fields = @{
    firstName = "Simon"
    lastName = "Buckley"
}

Update-BambooHRUser -apiKey "xxxxxxxxxxxxxxxxxxxxxxxxxxxx" -subDomain "companyname" -id 300 -fields $fields

If you don't have the employee's ID, you can use their email address instead. Note however, this performs a full directory lookup first, extracts the user's ID, and then performs the update request against that user's ID. If you have the employee's unique ID, using it instead will be considerably quicker.

Update-BambooHRUser -apiKey "xxxxxxxxxxxxxxxxxxxxxxxxxxxx" -subDomain "companyname" -emailAddress "[email protected]" -fields $fields

To add a new user to BambooHR, use the command below. Note: the BambooHR API expects a minimum of firstName and lastName for new users. The 'Fields' parameter expects a hash table of fields/values, as below.

New-BambooHRUser -apiKey "xxxxxxxxxxxxxxxxxxxxxxxxxxxx" -subDomain "companyname" -fields @{firstName="Simon";lastName="Buckley"}