2024.11.08 - Changes when Saving Employee Addresses

The employee API, when saving employee addresses, has been updated to improve clarity and functionality. Previously, the endpoint accepted full country names for saving addresses and allowed the use of a two-letter ISO code specifically for the United States. For other countries, if a two-letter ISO code, three-letter ISO code, or literally anything was used, the API would save the address but omit the country, leading to user confusion as they believed the country was saved. To address this issue, the API now requires a country to be specified for all addresses. It has been enhanced to accept country information in three formats: full country names, two-letter ISO codes, and BambooHR country IDs. This change ensures that all addresses are saved with a valid country, reducing confusion and improving the user experience.

2023.10.19 - Clean API aliases for custom fields

Previously, when a custom field was created for a customer by the BambooHR support team, an API alias would be automatically created without regard to any special characters in the field name. We've now altered that creation process so that only alphanumeric characters will exist in the field aliases, thus making them more usable in API integrations.

Example: if a custom field was created with the name Favorite food/drink, the alias the system generated would be customFavoritefood/drink. Now, a field with that name will have an alias of customFavoritefooddrink - no problematic slash in the middle of the name.

2023.01.16 - Adding a limit to the Get Employee Endpoint

In the next few days we will be setting a limit of up to 400 fields that can be requested for a single request to the Get Employee endpoint. This limit is being applied to help ensure the stability and performance of our
systems for everyone. We will communicate about any additional updates to this limit as needed.

2022.12.6 - Adding Limits to Custom Report Endpoints

We are currently researching a reasonable limit to the number of fields that can be requested in a single custom report. 90% of uses of the Request a custom report endpoint request 30 or less fields. However there are some requests that attempt to get 1000 or more fields in a single request. We will soon (within days) be implementing a limit of 400 fields on a single custom report request. We may lower that number further, but we don't anticipate going lower than 100. We will continue communicating about this as we find out more.

2022.07 - Goals Endpoints

New endpoints have been created to allow you to manage goals. Although first opened for use back in May, these endpoints have had some minor adjustments and as such there is some versioning. As you are using the endpoints, be aware of which version you are using to access the feature you need.

2022.04 - Beta Developer Webhooks

A new type of webhooks were created to be used by api. These webhooks are different than the webhooks that are managed directly in BambooHR. These will be created with the api user. As such the webhooks will only have access to fields that the api user has access to.

2022.04 - Table Delete Endpoint

A much requested feature, you are now able to delete table row information. More strictly table rows. Whenever you update information that is contained in a table, a new row is created. For whatever reason you may have you now are able to delete rows with this new endpoint.

2021.01 - Only Current Update for Employees

The get employee endpoint has been updated with the optional field onlyCurrent. With this field you can now specify if you want only the current employees or if you want to include future dated employees. This change has also been made to reporting, so you can use the same field when generating reports.

2021.12.02 - Change to Training Due Date Retrieved from the Reports API

We discovered a bug in our reporting system where the Training Due Date field was showing a date one day earlier than the dates shown in the Employee’s Training tab. We will be releasing a fix on December 2, 2021 that makes the Training Due Date in reports consistent with the dates in the Training tab.

We don’t anticipate any breaking changes to integrations as no endpoints will be changing. However, anyone using the Reports API to retrieve Training Due Dates should note that the values returned may be different once this release is rolled out.

2021.09.24 - Custom Reports Field Keys and Values Alignment

We discovered a bug in our custom reports API where the field keys and values were out of alignment in the returned json object when using a non-admin user. As seen below, sometimes the fields were out of order and sometimes they were simply dropped. This occurred because of some permissions as well as placement of calculated fields (things like full name which are a composite of data stored in several different columns or areas of our system).

In this image the user associated with the request on the right doesn’t have access to the address information. Note that the key/label is missing.

In these images, notice that the label for the custom text field actually appears next to the value for the employmentHistoryStatus.

The fix we made ensured that there is a correct mapping between keys and values. Given that the error had been around for some time, we know that some of you may have implemented workarounds to this behavior to ‘fix’ the keys in your integrations, likely reworking the mapping and filling in the missing data. We regret that our ‘fix’ will require you to remove your fix but moving forward you can be confident that our returned reports json objects will have the appropriate keys/labels for each of the values.

2019.10.01 - acaStatus Field Deprecation

In preparation for this year's ACA reporting, BambooHR will be making product changes that may affect API integrations that depend on the acaStatus field. In particular, this field is being deprecated on November 1, 2019.

The field will continue to be available to read and write in the API, but is likely to become stale over time, as customers begin to use a different method of tracking ACA status. We don't yet have a firm design for the new method of ACA tracking in the API. We will be making further announcements as the API design becomes more set.

The replacement for the soon to be deprecated acaStatus field will be the acaStatusCategory field. It will be a text field with the following return options: contractor, full-time, intern-compensated, intern-not-compensated, part-time-eligible, part-time-ineligible, seasonal, and terminated. This field can not be updated directly but is calculated based on mappings for employment statuses found on the employmentStatus table.

Stay tuned.

2019.08.27 - Request API: Make Start/End Date Fields Mandatory

Posted: June 2019
The Get Time Off Requests API endpoint currently gathers ALL time off requests from the beginning of time. For large companies who have a lot of requests, this can be rather slow and delivers a lot of less-than-useful data.

Because of this, our date range parameter (which was optional) will become mandatory on August, 27, 2019

📘

Get Time Off Requests Documentation

https://documentation.bamboohr.com/reference/time-off-get-time-off-requests-1

2019.07.19 - Bug Fix - Employee names not displayed in "Last Name, First Name_MiddleName" format

A reference to another employee should be expressed as last name-comma-first name-space-middle name. Example: "Smith, Robert James"

This was in fact returning as: "Robert James Smith"

2018.09 - JSON Endpoint Support

We've recently been looking at ways to improve the API, especially for those just starting to build integrations with BambooHR. In that effort, we identified some areas where XML was still required to communicate with our API. To make it easier to get started, we wanted to allow consumers to use a single preferred communication format.

We have updated all of our endpoints that accepted XML to also accept JSON. These endpoints will look at your Content-Type header to see whether to parse your content as XML or JSON. By default, they will parse your content as XML. If you specify "Content-Type: application/json", then your content will be parsed as JSON.

To see how you should format your JSON requests, check out the documentation: https://www.bamboohr.com/api/documentation/. We have updated each endpoint to include example JSON.

2018.02 - API Keys Update

Previously when viewing the list of API Keys you’ve created, there were no easy-to-read labels, and let’s face it, remembering which 24 character string of gibberish was assigned to which integration isn’t a skill most of us have.

To cure this, we've added a nice little pop-up during the key creation process that will prompt you for a key name. And, you can also edit existing keys to add labels to them as well.

We have also done a small security upgrade here because security is an important thing when working with employee information.

What this means to you is that where previously, you could retrieve existing keys, it is now a one-time deal. You have to grab that key during the creation process or create a new one if it has been misplaced or lost. After they are created, the key is now encrypted and tucked away for safekeeping.

2017.04 - Reporting Behavior For Calculated Fields And Pay Rate And Per Period Change

We have two changes we are making that we need to make you aware of.

1. There is a small change in how calculated fields will behave in reporting.

What are calculated fields?

Calculated fields are created using existing fields to derive a new value. For example, you can create a calculated field for when an employee is getting close to retiring. This would be created using the date of birth field and then adding 65 years. The new field can be used in reporting and other areas of Bamboo. It looks like any other field.

In reporting, if you had a calculated field present, it would show up empty unless you saved a new value over the default calculated value. On May 5th we will change reporting to always show a date, whether it is the calculated value or one that has been saved over the calculated value. Currently it only shows a value if a new value has been saved over it.

2. The employee compensation table will require both the paidPer AND the rate fields, if one or the other is provided. This change will take place on May 19th.

For example, when POSTing to the API endpoint

https://ourfavoritecustomer.bamboohr.com/api/gateway.php/ourfavoritecustomer/v1/employees/10001/tables/compensation

if your payload looks like this:

<row>
    <field id="startDate">2017-05-01</field>
    <field id="paidPer">Year</field>
    <field id="rate">10</field>
</row>

...then you'll insert a new row, visible on the employee's Compensation table on the Job tab, of $10/Year.

If your payload includes neither paidPer nor rate, you'll be fine. The pay rate will just be blank on the Compensation table like this:

<row>
    <field id="startDate">2017-05-01</field>
</row>

...is just fine.

IF, however, your payload looks like this:

<row>
    <field id="startDate">2017-05-01</field>
    <field id="paidPer">Year</field>
</row>

...or like this...

<row>
    <field id="startDate">2017-05-01</field>
    <field id="rate">10</field>
</row>

...then your API call will be rejected with a 406 NOT ACCEPTABLE status, with the following header returned to you:

X-BambooHR-ErrorMessage: Field errors: Pay (Both paidPer and rate are required when one or the other is given.)

2017.03 - Migration Of Termination Data

Last year we made a change to the termination process to add a termination row to the employment status table when you terminate an employee from that point forward.

Next week on Monday (March 13th) for terminations that happened before this change we will add a new row where there is a termination entry missing. This is to ensure accurate data for future product updates.

We wanted to give you noticed that you may see changes come through if you have web hooks set up based on the employment status table.

You might also see this change come through if you are using the Last Changed API endpoint. https://www.bamboohr.com/api/documentation/changes.php

2016.12 - Employment Status

There are three fields used with these endpoints: https://www.bamboohr.com/api/documentation/employees.php) with similar aliases in the API:

1. status
2. employmentStatus
3. employmentHistoryStatus

There is also a table (used with these endpoints: https://www.bamboohr.com/api/documentation/tables.php) with the alias "employmentHistoryStatus" that is NOT deprecated and will NOT be removed.

"status" is the "active", "inactive" status of the employee.

"employmentStatus" is an older name for the same field, and was deprecated due to its confusing name.

"employmentHistoryStatus" is the actual employment status of an employee, like "contractor", "full-time", "part-time", etc. and is a list of values that can be customized for your use. It is also associated with ACA status.

"employmentStatus", with its confusing name, has been deprecated for 3 years, and we will be removing it beginning April 1st, 2017. From what we can see, usage is very rare, so it's likely you will not affected. If you are using "employmentStatus", you can switch to "status" to get the exact same behavior.

2016.09 - Termination & Rehire Notification

OVERVIEW

-Future Dating (hires, terminations, job, compensation, and other table data)
-Rehiring
-Employment Status History

FUTURE DATING

Currently, any time you future date a hire date, termination date, or tabular data (Job Information, Compensation etc.) we recognize that information in Bamboo immediately. With the coming change we will only recognize the date when the date arrives.

REHIRING

The rehiring process has been simplified from several steps to just one.

EMPLOYMENT STATUS HISTORY

To accomplish future dating and a new rehire process we are going to upgrade the Employment Status table to track the employment history for an employee.

Terminations will be tracked in the Employment Status tabled along with the other termination fields. This will enable the historical tracking of termination information.

To terminate employees through the API, you may have previously made a request like:

POST /api/gateway.php/{company}/v1/employees/{number}

<employee>
    <field id="terminationDate">2016-08-01</field>
</employee>

The API field "terminationDate" will become a read-only field. It will continue to reflect the termination date of an employee if the employee is terminated, but in order to properly terminate an employee you will need to make a request like:

POST /api/gateway.php/{company}/v1_1/employees/{employeeid}/tables/employmentStatus

<employee>
    <field id="ymd">2016-08-01</field>
    <field id="employmentStatus">1234</field><!-- 1234 is the id of the "Terminated" list value in the employmentStatus list. →
    <!-- other termination fields will be available to update -->
</employee>

2015.05 - Company Directory API Update

COMPANY DIRECTORY
We are including more information for the company directory so the response matches the fields that are available in the web app.

The new API fields we added to the directory include:

<field id="gender">Gender</field>
  <field id="skypeUsername">Skype Username</field>
  <field id="aimUsername">AIM Username</field>
  <field id="windowsLiveMessenger">Windows Live Messenger</field>
  <field id="facebook">Facebook URL</field>
  <field id="linkedIn">LinkedIn URL</field>
  <field id="twitterFeed">Twitter Feed</field>
  <field id="pinterest">Pinterest URL</field>

The social fields will only get passed to the directory API call if they are enabled in the company directory settings and available as standard fields in the company.

The documentation on the current endpoint can be found here:
https://documentation.bamboohr.com/reference/get-employees-directory-1

TIME OFF TYPE CUSTOM COLOR
In our web app, we allow users to choose a custom color to represent a certain time off type (vacation, sick, etc.) to make it easy to distinguish on the calendar. We are extending the '/v1/meta/time_off/types/' endpoint to include the custom color in the response. Here's an example:

<timeOffType id="4">
  <name>Vacation</name>
  <units>hours</units>
  <color>4aada4</color>
 </timeOffType>

As you might guess, the color is the hex value. You may not need this for anything you are doing with the API, but you should be aware of the addition.