DocumentationAPI Reference
Documentation

Historical Changes to the API

Changes to the BambooHR API, newest first. Covers new endpoints, behavior and response changes, deprecations, and updates to the API reference.

About deprecated endpoints: A deprecated label identifies an older endpoint or authentication method for which BambooHR recommends a newer alternative. The label does not, by itself, announce a sunset or access cutoff. Unless a separate notice provides a sunset date, deprecated endpoints remain available to existing integrations. If BambooHR establishes a removal plan, we will communicate the timeline and migration guidance separately.

2026.08.10 – New Company Holiday and Holiday Catalog Endpoints

We added the following public API endpoints for finding holidays in the global holiday catalog and managing company holidays. Use the catalog endpoints to look up standard holidays and their UUIDs, then create company holidays from catalog entries or define them directly.

Holiday catalog

Company holidays

These endpoints support both Basic Auth and OAuth 2.0. Read operations use the holidays scope, while write operations use the holidays.write scope.

Review the linked documentation for more information.

2026.08.04 – New Legacy Report Field Map Endpoint

We added a companion to last month's ID map endpoint to help integrations finish the transition from legacy custom reports to our updated reporting infrastructure.

Get Legacy Report Field Map (GET /api/v1/custom-reports/legacy-field-map) returns a mapping from the field identifiers the deprecated Get Company Report endpoint returned to the field names the Custom Reports and Datasets endpoints use today. If your integration or automation still references legacy field identifiers, use this endpoint to look up the current name. A field that came back as location before report migration is jobInformationLocation afterward.

Key details:

  • Each mapping pairs a legacyFieldId with the fieldName it now maps to, along with that field's fieldLabel, type, and entityName. The fieldName matches the key returned by Get Report by ID and Get Fields from Dataset, so it needs no further translation.
  • Legacy time off, benefit, and training fields encoded a category in the field itself, so a legacy "Vacation" field returned only vacation hours. These map to a general field plus a qualifier you must apply as a filter. Requesting the mapped fieldName on its own returns every category rather than the one the legacy field returned.
  • A legacy identifier can appear more than once, because the legacy report emitted an amount column and its currency-code column under a single identifier. payRate maps to both compensationPayRate and compensationPayRateCurrencyCode, so compare type or fieldLabel against the column you are replacing. An identifier that is absent has no equivalent field, and the migrated report doesn't contain that column either.
  • The response is company-wide field metadata rather than report data, so it isn't scoped to your reports or your field permissions and a field appearing here doesn't mean you can read its data. The endpoint returns a 403 when the user doesn't have permission to manage reports.
  • Supports both Basic Auth and OAuth 2.0 with the report scope.

To translate legacy report IDs rather than field identifiers, use Get Legacy Report ID Map.

Full documentation is available under Get Legacy Report Field Map.

2026.08.03 – API Reference Sections Merged: Alerts

We combined two category names in the API reference into one:

  • "Alert" and "Alert Configurations" are now a single category, "Alerts."
  • All five alert endpoints, previously split across those two categories, now
    appear together under Alerts.

This is a category change only. The endpoint paths are unchanged.

2026.08.03 – Alert Template IDs Returned as Integers

List Alert Templates (GET /api/v1/alerts) now returns each alerts[].id
as an integer rather than a quoted string:

  • Before: {"id": "16", "name": "Birthday Summary"}
  • After: {"id": 16, "name": "Birthday Summary"}

The API reference already described this field as an integer, so this corrects
the response to match the documented type. It also means the value can be
passed directly as bambooAlertId when creating or replacing an alert
configuration, with no conversion. If your integration parses this field as a
string, update it accordingly.

2026.07.30 – Legacy Create Time Tracking Project Endpoint Marked Deprecated

We marked the legacy Create Time Tracking Project endpoint as deprecated in our OpenAPI documentation:

POST /api/v1/time_tracking/projects

For new development, use the current Create Time Tracking Project endpoint, which uses the newer contract:

POST /api/v1/time-tracking/projects

Note the path difference: the legacy endpoint uses time_tracking, while the current endpoint uses time-tracking.

This was a documentation and API metadata change. The deprecation annotation did not disable the legacy endpoint or remove access. No sunset date or removal timeline has been set, and existing integrations can continue using it. We recommend using the current endpoint for new development and planning a migration during future integration maintenance.

2026.07.29 – New Timesheet, Clock Entry, and Hour Entry Endpoints

We added the following public API endpoints for timesheets, clock entries, and hour entries:

Review the linked documentation for more information.

2026.07.23 – New Legacy Report ID Map Endpoint

We added a new endpoint to help integrations transition from legacy custom reports to our updated reporting infrastructure.

Get Legacy Report ID Map (GET /api/v1/custom-reports/legacy-id-map) returns a mapping from legacy custom report IDs to the new IDs created by report migration. If your integration or automation still references legacy report IDs, use this endpoint to look up the migrated ID, then pass that newReportId to Get Report by ID to run the migrated report.

Key details:

  • Each mapping pairs a legacyReportId with its newReportId and a status of migrated or notMigrated. When a report hasn't been migrated, newReportId is null.
  • Administrators receive mappings for every custom report in the company. Other users receive mappings only for reports they own or that are shared with them, so for non-admins, a missing legacy ID may simply be outside that user's visibility rather than nonexistent.
  • The endpoint returns a 403 when the user doesn't have permission to access reports at all. If the user has reports access but no legacy reports they owned or that were shared with them before migration, it returns a 200 with an empty mappings array.
  • Supports both Basic Auth and OAuth 2.0 with the report scope.

Full documentation is available under Get Legacy Report ID Map.

2026.07.08 – Employee Table and Time Off Policy v1 Endpoints Marked Deprecated

We marked the following v1 endpoints as deprecated in our OpenAPI documentation and added guidance directing new development to their v1.1 equivalents:

  • POST /api/v1/employees/{id}/tables/{table}
  • POST /api/v1/employees/{id}/tables/{table}/{rowId}
  • GET /api/v1/employees/{employeeId}/time_off/policies
  • PUT /api/v1/employees/{employeeId}/time_off/policies

The corresponding endpoints are available under /api/v1_1/.

The annotations did not disable these endpoints or remove access. No sunset date or removal timeline has been set, and existing integrations can continue using them. We recommend using v1.1 for new development and planning a migration during future integration maintenance.

2026.06.26 – New Shift Assessments Endpoint

We added the following public API endpoint for shift assessments:

Review the linked documentation for more information.

2026.06.11 – API Reference Sections Renamed: Change Tracking & Employee Tables

We updated two category names in the API reference and moved one endpoint between them:

  • "Last Change Information" is now "Change Tracking."
  • "Tabular Data" is now "Employee Tables."
  • Get Changed Employee Table Data (GET /employees/changed/tables/{table}) moved from Employee Tables into Change Tracking, so the two "what changed since" endpoints now sit together.

This is a category change only. None of the actual endpoints are affected.

2026.06.11 – New Shift Differential Endpoints (Time Tracking)

We added the following public API endpoints for managing Time Tracking shift differentials:

Review the linked documentation for more information.

2026.05.29 – New Schedule PDF Endpoint

We added the following public API endpoint for downloading schedules as PDFs:

Review the linked documentation for more information.

2026.05.18 – New Employee Verification Record Update Endpoint

We added the following public API endpoint for updating employee verification records:

Review the linked documentation for more information.

2026.05.13 – New Scheduling Endpoints

We added the following public API endpoints for Scheduling:

Review the linked documentation for more information.

2026.05.12 – New Employee Verification Integration and Lifecycle Email Endpoints

We added the following public API endpoints for managing the Employee Verification integration and sending lifecycle emails:

Review the linked documentation for more information.

2026.05.11 – New Employee Verification Records Endpoint

We added the following public API endpoint for listing an employee's verification records:

Review the linked documentation for more information.

2026.05.08 – New Onboarding Experience and New Hire Widget Endpoints

We added the following public API endpoints for employee onboarding experiences and the welcome new hires widget:

Review the linked documentation for more information.

2026.05.06 – New Hire Packet Delivery Endpoints

We added the following public API endpoints for sending and canceling new hire packets:

Review the linked documentation for more information.

2026.05.06 – New Currency Conversion Rates Endpoint

We added the following public API endpoint for currency conversion rates:

Review the linked documentation for more information.

2026.05.05 – New Hire Packet Management Endpoints

We added the following public API endpoints for creating, updating, and deleting new hire packets:

Review the linked documentation for more information.

2026.05.05 – New Country and Timezone Endpoints

We added the following public API endpoints for looking up countries and timezones:

Review the linked documentation for more information.

2026.05.04 – New Industries Endpoint

We added the following public API endpoint for listing industries:

Review the linked documentation for more information.

2026.05.01 – New Hire Packet Read Endpoints

We added the following public API endpoints for listing and retrieving new hire packets:

Review the linked documentation for more information.

2026.05.01 – New Break Policy Suggestions Endpoint

We added the following public API endpoint for break policy suggestions:

Review the linked documentation for more information.

2026.05.01 – New Compensation Planning Administration and Approval Endpoints

We added the following public API endpoints for Compensation Planning administrators, approval flows, and recommendations:

Review the linked documentation for more information.

2026.05.01 – New Province and Timezone Endpoints

We added the following public API endpoints for looking up provinces and timezones:

Review the linked documentation for more information.

2026.04.30 – New Total Rewards Endpoints

We added the following public API endpoints for Total Rewards:

Review the linked documentation for more information.

2026.04.30 – New Delete Employee Endpoint

We added the following public API endpoint for deleting employees:

Review the linked documentation for more information.

2026.04.30 – New Compensation Planning Cycle and Budget Endpoints

We added the following public API endpoints for managing Compensation Planning cycles, employees, and budgets:

Review the linked documentation for more information.

2026.04.30 – New Compensation Tools and Equity Settings Endpoints

We added the following public API endpoints for discovering compensation tools and managing company equity settings:

Review the linked documentation for more information.

2026.04.30 – New Company Properties and Currency Type Endpoints

We added the following public API endpoints for retrieving company properties and currency types:

Review the linked documentation for more information.

2026.04.29 – New Pay Grades & Bands Write Endpoints

We added the following public API endpoints for updating and publishing Pay Grades & Bands data:

Review the linked documentation for more information.

2026.04.29 – New Alert Template and Configuration Endpoints

We added the following public API endpoints for listing alert templates and managing alert configurations:

Review the linked documentation for more information.

2026.04.28 – New Bank Holidays Endpoint

We added the following public API endpoint for listing bank holidays:

Review the linked documentation for more information.

2026.04.27 – New Pay Grades & Bands Read Endpoints

We added the following public API endpoints for retrieving Pay Grades & Bands data:

Review the linked documentation for more information.

2026.04.27 – Time Tracking Project and Task Endpoints Added to the Public API Reference

We added the following public API endpoints for managing Time Tracking projects and tasks:

Create Time Tracking Project returns to the reference after being removed in April 2025.

Review the linked documentation for more information.

2026.04.24 – New Company Equity Settings Endpoint

We added the following public API endpoint for retrieving company equity settings:

Review the linked documentation for more information.

2026.04.20 – New Compensation Planning Read Endpoints

We added the following public API endpoints for reading Compensation Planning cycles, budgets, approvals, worksheets, and summaries:

Review the linked documentation for more information.

2026.04.17 – New Company Industry Codes Endpoint

We added the following public API endpoint for updating company industry codes:

Review the linked documentation for more information.

2026.04.16 – New Company Information Endpoint

We added the following public API endpoint for updating company contact, address, and legal-name information:

Review the linked documentation for more information.

2026.04.13 – New Get Data from Dataset v2 Endpoint

We added the following public API endpoint for retrieving data from datasets using v2:

Review the linked documentation for more information.

2026.04.13 – New Compensation Benchmarking Endpoints

We added the following public API endpoints for Compensation Benchmarking:

Review the linked documentation for more information.

2026.04.13 – New Company Display Name Endpoint

We added the following public API endpoint for updating a company's display name:

Review the linked documentation for more information.

2026.04.09 – Get Data from Dataset v1 Marked Deprecated

We marked POST /api/v1/datasets/{datasetName} as deprecated in our OpenAPI documentation and added guidance to use Get Data from Dataset v2:

POST /api/v2/datasets/{datasetName}/data

The annotation did not disable the v1 endpoint or remove access. No sunset date or removal timeline has been set, and existing integrations can continue using it. We recommend v2 for new development and encourage existing integrations to plan a migration when practical.

2026.04.02 – New Locations Endpoints

We added the following public API endpoints for Locations:

Review the linked documentation for more information.

2026.03.25 – Dataset Discovery v1 Endpoints Marked Deprecated

We marked the following Dataset discovery endpoints as deprecated in our OpenAPI documentation and added guidance directing consumers to the v1.2 versions:

  • GET /api/v1/datasets → GET /api/v1_2/datasets
  • GET /api/v1/datasets/{datasetName}/fields → GET /api/v1_2/datasets/{datasetName}/fields
  • POST /api/v1/datasets/{datasetName}/field-options → POST /api/v1_2/datasets/{datasetName}/field-options

The annotations did not disable the v1 endpoints or remove access. No sunset date or removal timeline has been set, and existing integrations can continue using them. We recommend v1.2 for new development because it provides standardized error responses and improved request tracing.

2026.03.18 – Legacy Report Endpoints Marked Deprecated

We marked two legacy report endpoints as deprecated in our OpenAPI documentation and added guidance directing consumers to their newer alternatives:

  • POST /api/v1/reports/custom → Get Data from Dataset v2 at POST /api/v2/datasets/{datasetName}/data
  • GET /api/v1/reports/{id} → Get Report by ID at GET /api/v1/custom-reports/{reportId}

The annotations did not disable the legacy endpoints or remove access. No sunset date or removal timeline has been set, and existing integrations can continue using them. We recommend the newer endpoints for new development and encourage existing integrations to evaluate migration during future maintenance.

2026.03.13 – New Timezones Endpoint

We added the following public API endpoint for listing timezones:

Review the linked documentation for more information.

2026.03.02 – New Company Profile Integrations Endpoint

We added the following public API endpoint for retrieving Company Profile integrations:

Review the linked documentation for more information.

2026.02.27 – New Webhook Post Fields Endpoint

We added the following public API endpoint for retrieving webhook post fields:

Review the linked documentation for more information.

2026.02.25 – New Meal & Rest Breaks Endpoints (Time Tracking)

We added the following public API endpoints for managing meal and rest breaks in Time Tracking. Use them to define break policies (including break type, duration, and timing rules), assign those policies to employees, and retrieve employee break availability and compliance assessments.

Break policies

Breaks within a policy

Policy assignments

Employee availability and assessments

For an overview of how these endpoints fit together, see Meal & Rest Breaks in the Time Tracking section.

2026.02.18 – Best Practice: Always Send Credentials With API Requests

In November 2025, we announced plans to remove the WWW-Authenticate: Basic realm="..." header from all API 401 responses. After further evaluation, we've taken a more targeted approach to avoid disrupting existing integrations.

When an API request is made without credentials, BambooHR returns a 401 with a WWW-Authenticate: Basic realm="..." header. Some HTTP clients treat that header as a signal to retry with credentials, a pattern known as HTTP authentication negotiation. While this is part of the HTTP spec, it doubles the round trips for every API call, adding latency and consuming rate limit budget on requests that will always fail.

We strongly recommend configuring your integration to include credentials on every API request from the start rather than relying on this challenge-response cycle. This eliminates the extra round trip, improves reliability by succeeding on the first attempt, and preserves your rate limit budget for productive calls. Most HTTP client libraries support sending credentials preemptively. Consult your library's documentation for how to send the Authorization header with every request.

Note that the WWW-Authenticate: Basic realm header will not be included in future API versions. For improved security and granular access control, we also recommend migrating to OAuth 2.0. See Getting Started With The API for details.

2026.01.23 – New Benefits Endpoints

We added the following public API endpoints for retrieving benefits data, helping partners in the benefits ecosystem support enrollment workflows and compliance reporting while reducing duplicate data entry:

  • List Company Benefits (GET /api/v1/benefit/company_benefit) returns the benefit plans a company offers, including plan identifiers, categories, effective dates, and catch-up contribution eligibility.
  • List Employee Benefits (GET /api/v1/benefit/employee_benefit) returns employee enrollment records, including coverage level, enrollment status, and employee and employer contribution details.
  • List Member Benefits (GET /api/v1/benefits/member-benefits) returns member-level benefits data scoped to a calendar year. A member may be an employee or a dependent.

These endpoints support both Basic Auth and OAuth 2.0 with the benefit scope.

For an overview of how these endpoints fit together, see Benefits.

2026.01.05 – New Dataset Field Options v1.2 Endpoint

We added the following public API endpoint for retrieving available field options from a dataset:

This completes the Datasets v1.2 discovery workflow alongside:

Together, these endpoints provide the same dataset and field-discovery capabilities as their v1 counterparts while introducing standardized RFC 7807 error responses, structured error codes, and X-Request-ID support for request tracing.

Existing integrations using v1 do not need to migrate immediately. We recommend that new integrations use the v1.2 endpoints for their improved response and error formats.

Review the linked documentation for more information.

2025.12.19 – New List Datasets v1.2 Endpoint

We added the following public API endpoint for listing available datasets:

This v1.2 endpoint returns standardized RFC 7807 error responses with structured error codes and supports X-Request-ID for request tracing. Existing integrations using the corresponding v1 endpoint do not need to migrate immediately.

Review the linked documentation for more information.

2025.12.11 – New Dataset Fields v1.2 Endpoint

We added the following public API endpoint for retrieving fields from a dataset:

This v1.2 endpoint returns standardized RFC 7807 error responses with structured error codes and supports X-Request-ID for request tracing. Existing integrations using the corresponding v1 endpoint do not need to migrate immediately.

Review the linked documentation for more information.

2025.10.02 – New List Employees Endpoint

We added the following public API endpoint for retrieving employee data:

It offers a more flexible way to retrieve employees than the directory endpoint or a custom report, letting you request only the employees and fields you need.

Key details:

  • Filter by fields such as first name, last name, job title, status, or employee IDs.
  • Sort by supported employee fields.
  • Cursor-based pagination for large result sets.
  • Select specific fields with the fields query parameter.
  • Supports both Basic Auth and OAuth 2.0 with the employees.read, employees:name.read, and employees:job.read scopes.

The existing directory endpoint and custom reports are unchanged, so no action is required for current integrations.

2025.09.22 – Webhooks for Custom Fields

We expanded our webhooks functionality to include support for custom fields, allowing customers and partners to monitor and receive real-time notifications when their own custom data changes.

Key Details:

  • Custom fields now supported: You can now configure webhooks to monitor changes to your company's custom fields in addition to standard fields.
  • Consistent experience across webhook types: Both global and permissioned webhooks now include custom fields in their "fields to monitor" lists.

Note: Fields within custom tables (and the tables themselves) are not currently supported.

This enhancement makes webhooks more flexible and powerful, enabling customers to trigger automations, integrations, and workflows based on the specific custom data they maintain in BambooHR.

2025.09.10 – New Country and Province Endpoints

We added the following public API endpoints for retrieving countries and their states or provinces:

Review the linked documentation for more information.

2025.08.05 – Webhooks Enhancements

We enhanced our webhooks functionality with several key improvements:

  • Webhooks enabled by default for all companies, with no need to contact support.
  • Support for delete operations in addition to create and update.
  • A new real-time event-based framework that allows us to expand coverage in the future, including custom fields and other areas of the product.
  • Field-specific notifications that only send data about the fields you're monitoring rather than the entire data tables the fields belong to.
  • Enhanced payloads with two new fields:
    • action indicates whether the employee was created, updated, or deleted
    • timestamp gives the ISO 8601 timestamp of when the change occurred
  • Improved reliability through comprehensive bug fixes.
  • Updated documentation with clearer explanations of webhook behavior.

All existing webhooks continued to work without any changes required. No action was needed from customers or partners.

2025.08.05 – Webhook Scheduling and Rate Limiting Features Removed

As part of our webhooks enhancements, we transitioned from a cron-based system to a real-time event-driven architecture. With this transition, we removed webhook scheduling and rate limiting features from the user interface as they are no longer needed for real-time delivery.

If your webhook configuration used scheduling or rate limiting features, your webhooks automatically transitioned to real-time delivery with no action required.

2025.08.05 – Webhook Fields Removed

As part of our webhooks enhancements, we removed some webhook fields. Some of these fields no longer exist in our database, while others had extremely low usage (some fields were used by only 1-3 customers). We reached out directly to impacted customers with specific details about which fields were removed and alternative ways to access this data through our public API.

If you didn't hear from us, your webhooks were not affected and no action was needed.

2025.07.03 – API Routing Centralization

We updated the routing for our public API to simplify the architecture and improve consistency. All API requests now use the {companyDomain}.bamboohr.com/api/ format, replacing the previous api.bamboohr.com/api/gateway.php/{companyDomain}/ structure.

Existing integrations using the previous URL structure will continue to function without any required changes. New integrations should use the updated format.

2025.05.12 – Legacy Login Endpoint Marked Deprecated

We marked POST /api/v1/login as deprecated in our OpenAPI documentation and added guidance recommending OAuth 2.0 for new integrations. OAuth 2.0 provides more secure, granular access without generating persistent API keys through the legacy login flow.

The annotation did not disable the endpoint or remove access from existing integrations. No sunset date or removal timeline has been set. Existing consumers can continue using the endpoint, while new integrations should use OAuth 2.0.

2025.04.22 – Time Tracking Project Endpoint Removed from the Public API Reference

We removed the following endpoint from the public API reference:

  • Create Time Tracking Project (POST /api/v1/time-tracking/projects)

2025.04.18 – New Goals Aggregate v1.1 and v1.2 Endpoints

We added the following public API endpoints for retrieving goal aggregates:

Review the linked documentation for more information.

2025.04.15 – Self-Registration Now Available for Developer Portal

Developers can now self-register for access to the Developer Portal. Previously, developers needed to contact BambooHR directly to gain access. Now, they can simply visit https://developers.bamboohr.com, register their organization, create an application, select the required scopes, and obtain a client ID and secret. These credentials can then be used to request OAuth tokens via our token endpoint, enabling secure access to the BambooHR API.

2025.04.14 – New Applications No Longer Support oidcLogin

New applications should no longer use the oidcLogin endpoint to authenticate. This marks the beginning of a gradual deprecation of our legacy User API Key login flow, which uses OpenID Connect to exchange the resulting id_token to generate a BambooHR API key. While existing applications may continue using oidcLogin (with the required legacy.login scope), we strongly recommend reviewing your implementation and planning a full transition to OAuth 2.0 access tokens. This change improves overall security and aligns with industry standards for authorization and authentication.

2025.04.03 – Get Goals Aggregate v1 Marked Deprecated

We marked GET /api/v1/performance/employees/{employeeId}/goals/aggregate as deprecated in our OpenAPI documentation. Consumers migrating today should use the latest version:

GET /api/v1_2/performance/employees/{employeeId}/goals/aggregate

The annotation did not disable the v1 endpoint or remove access. No sunset date or removal timeline has been set, and existing integrations can continue using it.

2025.04.02 – Older Goal Endpoint Versions Marked Deprecated

We added OpenAPI deprecation markers and replacement guidance to these older Goal endpoint versions:

  • Goal filters v1 and v1.1 → GET /api/v1_2/performance/employees/{employeeId}/goals/filters
  • Update Goal v1 → PUT /api/v1_1/performance/employees/{employeeId}/goals/{goalId}
  • Goals Aggregate v1.1 → GET /api/v1_2/performance/employees/{employeeId}/goals/aggregate

The annotations did not disable the older endpoints or remove access. No sunset dates or removal timelines have been set, and existing integrations can continue using them. We recommend the latest versions for new development.

2025.03.31 – OAuth 2.0 Now Supported for API Authentication

OAuth 2.0 is now supported as the primary authentication method for accessing the BambooHR API. This new standard replaces the need for legacy API key generation via the oidcLogin endpoint and aligns with modern security and authorization best practices. OAuth 2.0 enables more secure, flexible, and scalable integrations, including support for granular scopes and token-based authentication flows.

We encourage all new integrations to adopt OAuth 2.0 moving forward, and recommend that existing applications begin transitioning away from the User API Key login flow to ensure long-term compatibility.

2025.03.14 – New Employee Photo Endpoint

We added the following public API endpoint for retrieving employee photos:

Review the linked documentation for more information.

2025.03.10 – Restricting Access to Email Addresses in the /v1/meta/users/ Endpoint to Admin Users Only

Previously, any user who could create an API key could retrieve the email addresses of all users in their organization, including inactive users, regardless of their assigned permissions. We introduced a resource permission check to ensure that only admin users can access email addresses via the API.

Impact:

  • Non-admin users are no longer able to retrieve email addresses from the /v1/meta/users/ endpoint.
  • Admin users continue to have access to this data.

We recommend reviewing your API usage to ensure that any integrations relying on email addresses from this endpoint are being accessed by an admin user.

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.06 – 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 Custom Report endpoint request 30 or less fields. However there are some requests that attempt to get 1,000 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 – Goal Management Endpoints

We added public API endpoints for managing employee goals. These endpoints first became available for use in May 2022 and were adjusted before this release, so multiple versions exist. Check which version you're calling to make sure you're getting the behavior you expect.

2022.04 – Beta Developer Webhooks

We introduced a new type of webhook created and managed through the API rather than in the BambooHR web app.

These webhooks are created by the API user, so they can only access fields that user has permission to see. This differs from webhooks configured directly in BambooHR.

2022.04 – New Table Row Delete Endpoint

We added a public API endpoint for deleting rows from employee tables.

Updating information stored in a table creates a new row rather than replacing the existing one, so tables accumulate history. This endpoint lets you remove individual rows.

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 Get Company Report endpoint 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.

954

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

933

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.

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.

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

ParametersBefore 08/27/2019Today
start - Only show time off that occurs on/after the specified start dateOptionalRequired
end - Only show time off that occurs on/before the specified end date.OptionalRequired
📘

Get Time Off Requests Documentation

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

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, 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.

  1. 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://{companyDomain}.bamboohr.com/api/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 notice 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 be 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 https://{companyDomain}.bamboohr.com/api/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 https://{companyDomain}.bamboohr.com/api/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 Fields Expanded

We expanded the response from GET /api/v1/employees/directory to match the fields available in the web app. The directory now includes gender and a set of social and messaging fields: Skype username, AIM username, Windows Live Messenger, Facebook URL, LinkedIn URL, Twitter feed, and Pinterest URL.

The social and messaging fields are returned only when they are enabled in the company directory settings and available as standard fields for the company.

Full documentation is available under Get Employees Directory.

2015.05 – Time Off Type Custom Colors Added to the API

The GET /api/v1/meta/time_off/types endpoint now returns the custom color assigned to each time off type, matching the colors users select in the web app to distinguish types on the calendar. The color value is returned as a six-character hexadecimal code without a leading #.

Full documentation is available under List Time Off Types.

Updated about 11 hours ago