--- updatedAt: 2026-08-11T22:31:09.000Z --- Fetch the complete documentation index at: https://documentation.bamboohr.com/llms.txt. Use this file to discover all available pages before exploring further. # 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** * [List Catalog Holidays](https://documentation.bamboohr.com/reference/list-catalog-holidays) (`GET /api/v1/holidays/catalog`) * [Get Catalog Holiday](https://documentation.bamboohr.com/reference/get-catalog-holiday) (`GET /api/v1/holidays/catalog/{uuid}`) **Company holidays** * [List Company Holidays](https://documentation.bamboohr.com/reference/list-company-holidays) (`GET /api/v1/holidays`) * [Get Company Holiday](https://documentation.bamboohr.com/reference/get-company-holiday) (`GET /api/v1/holidays/{id}`) * [Create Company Holiday](https://documentation.bamboohr.com/reference/create-company-holiday) (`POST /api/v1/holidays`) * [Bulk Create Company Holidays](https://documentation.bamboohr.com/reference/bulk-insert-company-holidays) (`POST /api/v1/holidays/bulk-insert`) * [Update Company Holiday](https://documentation.bamboohr.com/reference/update-company-holiday) (`PATCH /api/v1/holidays/{id}`) * [Delete Company Holiday](https://documentation.bamboohr.com/reference/delete-company-holiday) (`DELETE /api/v1/holidays/{id}`) 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](https://documentation.bamboohr.com/reference/get-company-report) endpoint returned to the field names the [Custom Reports](https://documentation.bamboohr.com/reference/list-reports) and [Datasets](https://documentation.bamboohr.com/reference/list-datasets-v1) 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](https://documentation.bamboohr.com/reference/get-report-by-id) and [Get Fields from Dataset](https://documentation.bamboohr.com/reference/get-fields-from-dataset-v1), 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](https://documentation.bamboohr.com/reference/get-legacy-report-id-map). Full documentation is available under [Get Legacy Report Field Map](https://documentation.bamboohr.com/reference/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: * [Approve Timesheet](https://documentation.bamboohr.com/reference/approve-timesheet) (`POST /api/v1/time-tracking/timesheet-approvals`) * [Clock In](https://documentation.bamboohr.com/reference/clock-in) (`POST /api/v1/time-tracking/clock-ins`) * [Clock Out](https://documentation.bamboohr.com/reference/clock-out) (`POST /api/v1/time-tracking/clock-outs`) * [Create Clock Entry](https://documentation.bamboohr.com/reference/create-clock-entry) (`POST /api/v1/time-tracking/clock-entries`) * [Create Hour Entry](https://documentation.bamboohr.com/reference/create-hour-entry) (`POST /api/v1/time-tracking/hour-entries`) * [Delete Clock Entry](https://documentation.bamboohr.com/reference/delete-clock-entry) (`DELETE /api/v1/time-tracking/clock-entries/{id}`) * [Delete Hour Entry](https://documentation.bamboohr.com/reference/delete-hour-entry) (`DELETE /api/v1/time-tracking/hour-entries/{id}`) * [Get Clock Entry](https://documentation.bamboohr.com/reference/get-clock-entry) (`GET /api/v1/time-tracking/clock-entries/{id}`) * [Get Hour Entry](https://documentation.bamboohr.com/reference/get-hour-entry) (`GET /api/v1/time-tracking/hour-entries/{id}`) * [Get Timesheet](https://documentation.bamboohr.com/reference/get-timesheet) (`GET /api/v1/time-tracking/timesheets/{id}`) * [Get Timesheet Summary](https://documentation.bamboohr.com/reference/get-timesheet-summary) (`GET /api/v1/time-tracking/timesheets/{id}/summary`) * [List Clock Entries](https://documentation.bamboohr.com/reference/list-clock-entries) (`GET /api/v1/time-tracking/clock-entries`) * [List Hour Entries](https://documentation.bamboohr.com/reference/list-hour-entries) (`GET /api/v1/time-tracking/hour-entries`) * [List Timesheets](https://documentation.bamboohr.com/reference/list-timesheets) (`GET /api/v1/time-tracking/timesheets`) * [Update Clock Entry](https://documentation.bamboohr.com/reference/update-clock-entry) (`PATCH /api/v1/time-tracking/clock-entries/{id}`) * [Update Hour Entry](https://documentation.bamboohr.com/reference/update-hour-entry) (`PATCH /api/v1/time-tracking/hour-entries/{id}`) 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](https://documentation.bamboohr.com/reference/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](https://documentation.bamboohr.com/reference/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: * [List Shift Assessments](https://documentation.bamboohr.com/reference/scheduling-list-shift-assessments) (`GET /api/v1/scheduling/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: * [Create Time Tracking Shift Differential](https://documentation.bamboohr.com/reference/create-shift-differential) (`POST /api/v1/time-tracking/shift-differentials`) * [Delete Time Tracking Shift Differential](https://documentation.bamboohr.com/reference/delete-shift-differential) (`DELETE /api/v1/time-tracking/shift-differentials/{id}`) * [Get Time Tracking Shift Differential](https://documentation.bamboohr.com/reference/get-shift-differential) (`GET /api/v1/time-tracking/shift-differentials/{id}`) * [List Time Tracking Shift Differentials](https://documentation.bamboohr.com/reference/list-shift-differentials) (`GET /api/v1/time-tracking/shift-differentials`) * [Update Time Tracking Shift Differential](https://documentation.bamboohr.com/reference/update-shift-differential) (`PATCH /api/v1/time-tracking/shift-differentials/{id}`) 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: * [Get Schedule PDF](https://documentation.bamboohr.com/reference/scheduling-get-schedule-pdf) (`GET /api/v1/scheduling/schedules/{id}/pdf`) 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: * [Update an employee verification record](https://documentation.bamboohr.com/reference/update-employee-verification) (`PUT /api/v1/employee-verifications/employees/{employeeId}/{verificationId}`) Review the linked documentation for more information. ## 2026.05.13 – New Scheduling Endpoints We added the following public API endpoints for Scheduling: * [Create Schedule](https://documentation.bamboohr.com/reference/scheduling-create-schedule) (`POST /api/v1/scheduling/schedules`) * [Create Shift](https://documentation.bamboohr.com/reference/scheduling-create-shift) (`POST /api/v1/scheduling/shifts`) * [Delete Schedule](https://documentation.bamboohr.com/reference/scheduling-delete-schedule) (`DELETE /api/v1/scheduling/schedules/{id}`) * [Delete Shift](https://documentation.bamboohr.com/reference/scheduling-delete-shift) (`DELETE /api/v1/scheduling/shifts/{id}`) * [Get Schedule](https://documentation.bamboohr.com/reference/scheduling-get-schedule) (`GET /api/v1/scheduling/schedules/{id}`) * [Get Shift](https://documentation.bamboohr.com/reference/scheduling-get-shift) (`GET /api/v1/scheduling/shifts/{id}`) * [List Schedules](https://documentation.bamboohr.com/reference/scheduling-list-schedules) (`GET /api/v1/scheduling/schedules`) * [List Shifts](https://documentation.bamboohr.com/reference/scheduling-list-shifts) (`GET /api/v1/scheduling/shifts`) * [List Timezones](https://documentation.bamboohr.com/reference/scheduling-list-timezones) (`GET /api/v1/scheduling/timezones`) * [Publish Shifts](https://documentation.bamboohr.com/reference/scheduling-publish-shifts) (`POST /api/v1/scheduling/shifts/publish`) * [Update Schedule](https://documentation.bamboohr.com/reference/scheduling-update-schedule) (`PATCH /api/v1/scheduling/schedules/{id}`) * [Update Shift](https://documentation.bamboohr.com/reference/scheduling-update-shift) (`PATCH /api/v1/scheduling/shifts/{id}`) 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: * [Enable or disable the employee verification integration](https://documentation.bamboohr.com/reference/update-employee-verification-integration) (`PUT /api/v1/employee-verifications/integration`) * [Get employee verification integration status](https://documentation.bamboohr.com/reference/get-employee-verification-integration) (`GET /api/v1/employee-verifications/integration`) * [Send employee verification lifecycle email by user and email type](https://documentation.bamboohr.com/reference/send-employee-verification-lifecycle-email-by-user) (`POST /api/v1/employee-verifications/users/{userId}/send-email`) 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: * [List employee verification records for an employee](https://documentation.bamboohr.com/reference/list-employee-verifications-by-employee) (`GET /api/v1/employee-verifications/employees/{employeeId}`) 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: * [Create employee onboarding experience](https://documentation.bamboohr.com/reference/288aa996aba16d7a495c62321ea999a9) (`POST /api/v1/employees/{employeeId}/onboarding-experiences`) * [Get employee onboarding experience by id](https://documentation.bamboohr.com/reference/847dd061d1d1859e7ce8cb3adfc9faf2) (`GET /api/v1/employees/{employeeId}/onboarding-experiences/{onboardingExperienceId}`) * [Get welcome new hires widget](https://documentation.bamboohr.com/reference/044949386f2d655c6a627ef53f9434b7) (`GET /api/v1/onboarding/new-hire-widget`) * [List employee onboarding experiences](https://documentation.bamboohr.com/reference/0158de7cde2a4c4cf577f0b25070d809) (`GET /api/v1/employees/{employeeId}/onboarding-experiences`) * [Update GTKY answer visibility for a new hire packet](https://documentation.bamboohr.com/reference/update-new-hire-packet-gtky-answer-visibility) (`PUT /api/v1/new-hire-packets/{id}/question-visibility`) 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: * [Cancel new hire packet](https://documentation.bamboohr.com/reference/19c7e26a1347ae7eb22919e9b0595c19) (`POST /api/v1/new-hire-packets/{id}/cancel`) * [Send new hire packet](https://documentation.bamboohr.com/reference/f49b0f1f2fb1ef2c408ba12916ee9baa) (`POST /api/v1/new-hire-packets/{id}/send`) 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: * [Get Currency Conversion Rates](https://documentation.bamboohr.com/reference/get-currency-conversions) (`GET /api/v1/meta/currency-conversions`) 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: * [Create new hire packet](https://documentation.bamboohr.com/reference/ec1ba8e76f33960b018d0d7518fe97b5) (`POST /api/v1/new-hire-packets`) * [Delete new hire packet](https://documentation.bamboohr.com/reference/caa7fc488bcfaef14125398f2ebb987d) (`DELETE /api/v1/new-hire-packets/{id}`) * [Update new hire packet](https://documentation.bamboohr.com/reference/1ab0279d46023eb951a434f24df885f1) (`PUT /api/v1/new-hire-packets/{id}`) 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: * [Get Country by ID](https://documentation.bamboohr.com/reference/get-country-by-id) (`GET /api/v1/meta/countries/{id}`) * [Get timezone by ZIP code](https://documentation.bamboohr.com/reference/10d66d8561dd7dac50ff9c21ef63d83b) (`GET /api/v1/meta/timezones/by-zip/{zip}`) Review the linked documentation for more information. ## 2026.05.04 – New Industries Endpoint We added the following public API endpoint for listing industries: * [List Industries](https://documentation.bamboohr.com/reference/list-industries) (`GET /api/v1/meta/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: * [Get new hire packet by id](https://documentation.bamboohr.com/reference/696f0a229cdde60b733568e3c4d043d9) (`GET /api/v1/new-hire-packets/{id}`) * [List new hire packets](https://documentation.bamboohr.com/reference/f44b802c30cdea2b9076b3f82f99c74d) (`GET /api/v1/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: * [Get Break Policy Suggestions](https://documentation.bamboohr.com/reference/get-break-policy-suggestions) (`POST /api/v1/time-tracking/break-policies/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: * [Add cycle admins](https://documentation.bamboohr.com/reference/c7c32ed5278ac67e2e518bf7484a75dc) (`POST /api/v1/compensation/planning_cycles/{id}/admins`) * [Remove cycle admin](https://documentation.bamboohr.com/reference/ef7619b0ee4c8dc079aaea870cfbe81b) (`DELETE /api/v1/compensation/planning_cycles/{id}/admins/{employeeId}`) * [Remove from approval flow](https://documentation.bamboohr.com/reference/b1e467e0eef72350eec61fcfeaf4e19d) (`DELETE /api/v1/compensation/planning_cycles/{id}/approvals/employee/{employeeId}`) * [Save change comm template](https://documentation.bamboohr.com/reference/c79f9c5950f983e59d2626faa30c00a1) (`PUT /api/v1/compensation/planning_cycles/{id}/change_comm/template`) * [Save recommendations](https://documentation.bamboohr.com/reference/f3883a522dadbe9e11b34f8b656e3adb) (`POST /api/v1/compensation/planning_cycles/{id}/recommendations`) * [Send recommendations to next stage](https://documentation.bamboohr.com/reference/a05b6d5f564f805d688ff2c1e37c3990) (`POST /api/v1/compensation/planning_cycles/{id}/recommendations/send`) * [Set final approver](https://documentation.bamboohr.com/reference/5c4aab35a34f5760ec044104b5232bf5) (`POST /api/v1/compensation/planning_cycles/{id}/approvals/final_approver/{employeeId}`) * [Update approval flow](https://documentation.bamboohr.com/reference/cf87b8e09a001b6fb81dfce6c20ab9e3) (`PUT /api/v1/compensation/planning_cycles/{id}/approvals/{templateId}`) 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: * [Get All Provinces](https://documentation.bamboohr.com/reference/get-all-provinces) (`GET /api/v1/meta/provinces`) * [Get timezone by ID](https://documentation.bamboohr.com/reference/baa7162824294d030115568d1d8e6ca7) (`GET /api/v1/meta/timezones/{id}`) Review the linked documentation for more information. ## 2026.04.30 – New Total Rewards Endpoints We added the following public API endpoints for Total Rewards: * [Add Employees to Total Rewards](https://documentation.bamboohr.com/reference/add-total-rewards-employees) (`POST /api/v1/compensation/total_rewards/employees`) * [Check Total Rewards Profile Availability](https://documentation.bamboohr.com/reference/check-total-rewards-profile) (`GET /api/v1/compensation/total_rewards/{employeeId}`) * [Get Printable Total Rewards Statement](https://documentation.bamboohr.com/reference/get-total-rewards-printable-statement) (`GET /api/v1/compensation/total_rewards/{employeeId}/printable`) * [Get Total Rewards Statement](https://documentation.bamboohr.com/reference/get-total-rewards-statement) (`GET /api/v1/compensation/total_rewards/{employeeId}/statement`) * [Remove Employees from Total Rewards](https://documentation.bamboohr.com/reference/remove-total-rewards-employees) (`DELETE /api/v1/compensation/total_rewards/employees`) * [Remove Total Rewards Custom Disclaimer](https://documentation.bamboohr.com/reference/remove-total-rewards-custom-disclaimer) (`DELETE /api/v1/compensation/total_rewards/custom_disclaimer`) * [Set Total Rewards Custom Disclaimer](https://documentation.bamboohr.com/reference/set-total-rewards-custom-disclaimer) (`PUT /api/v1/compensation/total_rewards/custom_disclaimer`) * [Set Total Rewards Onboarding Step Status](https://documentation.bamboohr.com/reference/set-total-rewards-onboarding-step) (`PUT /api/v1/compensation/total_rewards/onboarding/{stepName}`) Review the linked documentation for more information. ## 2026.04.30 – New Delete Employee Endpoint We added the following public API endpoint for deleting employees: * [Delete employee](https://documentation.bamboohr.com/reference/delete-employee) (`DELETE /api/v1/employees/{id}`) 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: * [Add employees to cycle](https://documentation.bamboohr.com/reference/3958585c861325ea7a2cd30a8c74f042) (`POST /api/v1/compensation/planning_cycles/{id}/employees`) * [Complete compensation planning cycle](https://documentation.bamboohr.com/reference/f4b431363af6573af46750f32632e88b) (`PUT /api/v1/compensation/planning_cycles/{id}/complete`) * [Create compensation planning cycle](https://documentation.bamboohr.com/reference/e2ac4e1535f296cb8901f209e04caa83) (`POST /api/v1/compensation/planning_cycles`) * [Delete compensation planning cycle](https://documentation.bamboohr.com/reference/22ad75be25455279e2987c80851af5fc) (`DELETE /api/v1/compensation/planning_cycles/{id}`) * [Import budget breakdown](https://documentation.bamboohr.com/reference/1d1fc0f164cb51973a0206b8e2fb2d2d) (`POST /api/v1/compensation/planning_cycles/{id}/budgets/import`) * [Launch compensation planning cycle](https://documentation.bamboohr.com/reference/3a19f07aa737dc826ba43b9a1c1cd257) (`PUT /api/v1/compensation/planning_cycles/{id}/launch`) * [Remove employees from cycle](https://documentation.bamboohr.com/reference/89a5068111ec499135c7d6e9a53d5a30) (`DELETE /api/v1/compensation/planning_cycles/{id}/employees`) * [Save budget breakdown](https://documentation.bamboohr.com/reference/1d64402ee192568adbd5e3179a91e6e2) (`PUT /api/v1/compensation/planning_cycles/{id}/budgets/breakdown`) * [Save budget guidelines](https://documentation.bamboohr.com/reference/dacd313af2106213fc4696175941ce65) (`PUT /api/v1/compensation/planning_cycles/{id}/budgets/guidelines`) * [Update compensation planning cycle](https://documentation.bamboohr.com/reference/100b0cf8c5207b35697ff10370fd5fe1) (`PUT /api/v1/compensation/planning_cycles/{id}`) 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: * [List available compensation tools](https://documentation.bamboohr.com/reference/9f398e2652ea47a6dc5121ce5184222a) (`GET /api/v1/compensation/tools`) * [Update company equity settings](https://documentation.bamboohr.com/reference/c5880b509783cd9d7fce9ddf5d6af1be) (`PUT /api/v1/compensation/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: * [Get all currency types](https://documentation.bamboohr.com/reference/get-all-currency-types) (`GET /api/v1/meta/currency/types`) * [Get company properties](https://documentation.bamboohr.com/reference/get-meta-company) (`GET /api/v1/meta/company`) 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: * [Delete Compensation Level Groups or Level](https://documentation.bamboohr.com/reference/delete-compensation-level-groups-or-level) (`DELETE /api/v1/pay-grades-and-bands/levels/{segment}`) * [Publish Draft Compensation Level Groups](https://documentation.bamboohr.com/reference/publish-draft-compensation-level-groups) (`POST /api/v1/pay-grades-and-bands/publish`) * [Replace Job Title Level Assignments](https://documentation.bamboohr.com/reference/replace-job-title-level-assignments) (`PUT /api/v1/pay-grades-and-bands/job-titles`) * [Update Compensation Level Groups and Levels](https://documentation.bamboohr.com/reference/update-compensation-level-groups-and-levels) (`PUT /api/v1/pay-grades-and-bands/levels`) * [Update Pay Bands](https://documentation.bamboohr.com/reference/update-pay-bands) (`PUT /api/v1/pay-grades-and-bands/pay-bands`) * [Upload Levels and Bands CSV](https://documentation.bamboohr.com/reference/upload-levels-and-bands-csv) (`POST /api/v1/pay-grades-and-bands/import`) 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: * [Create Alert Configuration](https://documentation.bamboohr.com/reference/create-alert-configuration) (`POST /api/v1/alert-configurations`) * [Get Alert Configuration](https://documentation.bamboohr.com/reference/get-alert-configuration) (`GET /api/v1/alert-configurations/{id}`) * [List Alert Configurations](https://documentation.bamboohr.com/reference/list-alert-configurations) (`GET /api/v1/alert-configurations`) * [List Alert Templates](https://documentation.bamboohr.com/reference/list-alert-templates) (`GET /api/v1/alerts`) * [Replace Alert Configuration](https://documentation.bamboohr.com/reference/replace-alert-configuration) (`PUT /api/v1/alert-configurations/{id}`) 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: * [List Bank Holidays](https://documentation.bamboohr.com/reference/list-bank-holidays) (`GET /api/v1/meta/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: * [Get Compensation Level Group Status Counts](https://documentation.bamboohr.com/reference/get-compensation-level-group-status-counts) (`GET /api/v1/pay-grades-and-bands/status-counts`) * [Get Job Titles and Level Assignments](https://documentation.bamboohr.com/reference/get-job-title-level-assignments) (`GET /api/v1/pay-grades-and-bands/job-titles`) * [Get Levels and Bands Review](https://documentation.bamboohr.com/reference/get-levels-and-bands-review) (`GET /api/v1/pay-grades-and-bands/review`) * [Get Levels and Bands Status](https://documentation.bamboohr.com/reference/get-levels-and-bands-status) (`GET /api/v1/pay-grades-and-bands/status`) * [Get Pay Bands](https://documentation.bamboohr.com/reference/get-pay-bands) (`GET /api/v1/pay-grades-and-bands/pay-bands`) * [Get Published Levels and Bands](https://documentation.bamboohr.com/reference/get-published-levels-and-bands) (`GET /api/v1/pay-grades-and-bands`) * [List Compensation Level Groups and Levels](https://documentation.bamboohr.com/reference/list-compensation-level-groups-and-levels) (`GET /api/v1/pay-grades-and-bands/levels`) * [List Job Titles with Employees](https://documentation.bamboohr.com/reference/list-job-titles-with-employees) (`GET /api/v1/pay-grades-and-bands/job-titles-with-employees`) 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](https://documentation.bamboohr.com/reference/create-time-tracking-project) (`POST /api/v1/time-tracking/projects`) * [Create Time Tracking Project Task](https://documentation.bamboohr.com/reference/create-project-task) (`POST /api/v1/time-tracking/projects/{projectId}/tasks`) * [Delete Time Tracking Project](https://documentation.bamboohr.com/reference/delete-project) (`DELETE /api/v1/time-tracking/projects/{id}`) * [Delete Time Tracking Task](https://documentation.bamboohr.com/reference/delete-task) (`DELETE /api/v1/time-tracking/tasks/{id}`) * [Get Time Tracking Project](https://documentation.bamboohr.com/reference/get-project) (`GET /api/v1/time-tracking/projects/{projectId}`) * [Get Time Tracking Task](https://documentation.bamboohr.com/reference/get-task) (`GET /api/v1/time-tracking/tasks/{id}`) * [List Time Tracking Project Tasks](https://documentation.bamboohr.com/reference/list-project-tasks) (`GET /api/v1/time-tracking/projects/{projectId}/tasks`) * [List Time Tracking Projects](https://documentation.bamboohr.com/reference/list-projects) (`GET /api/v1/time-tracking/projects`) * [Update Time Tracking Project](https://documentation.bamboohr.com/reference/update-project) (`PATCH /api/v1/time-tracking/projects/{id}`) * [Update Time Tracking Task](https://documentation.bamboohr.com/reference/update-task) (`PATCH /api/v1/time-tracking/tasks/{id}`) 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: * [Get company equity settings](https://documentation.bamboohr.com/reference/db49fb29f9f04d59afad7c01ce860418) (`GET /api/v1/compensation/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: * [Export compensation planning cycle worksheet to CSV](https://documentation.bamboohr.com/reference/593d5bff120edf2a218a92022a682728) (`GET /api/v1/compensation/planning_cycles/{id}/worksheet/export`) * [Get change communication letter details](https://documentation.bamboohr.com/reference/d6987e300672a00c7cfe59afebb64156) (`GET /api/v1/compensation/planning_cycles/{id}/change_comm`) * [Get compensation planning approval flows](https://documentation.bamboohr.com/reference/4e886b18264480611f380805301c49c4) (`GET /api/v1/compensation/planning_cycles/{id}/approvals`) * [Get compensation planning cycle budgets](https://documentation.bamboohr.com/reference/7efceaee2c010f88244dd01ee81e6e7b) (`GET /api/v1/compensation/planning_cycles/{id}/budgets`) * [Get compensation planning cycle details](https://documentation.bamboohr.com/reference/5c2b55158b0950b1e9211655666645b6) (`GET /api/v1/compensation/planning_cycles/{id}`) * [Get compensation planning cycle summary](https://documentation.bamboohr.com/reference/9bc279d788f6e86b4cd8b2e0d3de91b1) (`GET /api/v1/compensation/planning_cycles/{id}/summary`) * [Get compensation planning cycle worksheet](https://documentation.bamboohr.com/reference/329acecaa6df729733d0752aa9f6b204) (`GET /api/v1/compensation/planning_cycles/{id}/worksheet`) * [List compensation planning cycle admins](https://documentation.bamboohr.com/reference/b3c51254de6918637a971fe4af382a53) (`GET /api/v1/compensation/planning_cycles/{id}/admins`) * [List compensation planning cycles](https://documentation.bamboohr.com/reference/b65f246186b41a9783a9397c11c703b4) (`GET /api/v1/compensation/planning_cycles`) * [List employees in compensation planning cycle](https://documentation.bamboohr.com/reference/a6b8da1348a3151fe95adc03aaf64447) (`GET /api/v1/compensation/planning_cycles/{id}/employees`) 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: * [Update Company Industry Codes](https://documentation.bamboohr.com/reference/put-company-industry-codes) (`PUT /api/v1/company-profile-data/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: * [Update company information (phone, address, legal name)](https://documentation.bamboohr.com/reference/patch-company-profile-company-information) (`PATCH /api/v1/company-profile-data/company-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: * [Get Data from Dataset (v2)](https://documentation.bamboohr.com/reference/get-data-from-dataset-v2) (`POST /api/v2/datasets/{datasetName}/data`) Review the linked documentation for more information. ## 2026.04.13 – New Compensation Benchmarking Endpoints We added the following public API endpoints for Compensation Benchmarking: * [Create Compensation Benchmark](https://documentation.bamboohr.com/reference/create-compensation-benchmark) (`POST /api/v1/compensation/benchmarks`) * [Create Compensation Benchmark Source](https://documentation.bamboohr.com/reference/create-compensation-benchmark-source) (`POST /api/v1/compensation/benchmarks/sources`) * [Delete Compensation Benchmark](https://documentation.bamboohr.com/reference/delete-compensation-benchmark) (`DELETE /api/v1/compensation/benchmarks/{id}`) * [Delete Compensation Benchmark Source](https://documentation.bamboohr.com/reference/delete-compensation-benchmark-source) (`DELETE /api/v1/compensation/benchmarks/sources`) * [Export Compensation Benchmark Details](https://documentation.bamboohr.com/reference/export-compensation-benchmark-details) (`GET /api/v1/compensation/benchmarks/details/export`) * [Get Compensation Benchmark Details](https://documentation.bamboohr.com/reference/get-compensation-benchmark-details) (`GET /api/v1/compensation/benchmarks/details`) * [Import Compensation Benchmarks From CSV](https://documentation.bamboohr.com/reference/import-compensation-benchmarks) (`POST /api/v1/compensation/benchmarks/import`) * [List Compensation Benchmark Sources](https://documentation.bamboohr.com/reference/list-compensation-benchmark-sources) (`GET /api/v1/compensation/benchmarks/sources`) * [List Compensation Benchmarks](https://documentation.bamboohr.com/reference/list-compensation-benchmarks) (`GET /api/v1/compensation/benchmarks`) * [Update Compensation Benchmark](https://documentation.bamboohr.com/reference/update-compensation-benchmark) (`PUT /api/v1/compensation/benchmarks`) * [Update Compensation Benchmark Sources](https://documentation.bamboohr.com/reference/update-compensation-benchmark-sources) (`PUT /api/v1/compensation/benchmarks/sources`) 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: * [Update company display name](https://documentation.bamboohr.com/reference/put-company-profile-display-name) (`PUT /api/v1/company-profile-data/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: * [Create a job location](https://documentation.bamboohr.com/reference/create-location) (`POST /api/v1/hris/org/locations`) * [Delete a job location](https://documentation.bamboohr.com/reference/delete-location) (`DELETE /api/v1/hris/org/locations/{id}`) * [Get a job location](https://documentation.bamboohr.com/reference/get-location) (`GET /api/v1/hris/org/locations/{id}`) * [List job locations](https://documentation.bamboohr.com/reference/get-locations) (`GET /api/v1/hris/org/locations`) * [Update a job location](https://documentation.bamboohr.com/reference/update-location) (`PUT /api/v1/hris/org/locations/{id}`) 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: * [List timezones](https://documentation.bamboohr.com/reference/5c5fb0f1211ae1c9451753f92f1053b6) (`GET /api/v1/meta/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: * [Get Company Profile Integrations](https://documentation.bamboohr.com/reference/get-company-profile-integrations) (`GET /api/v1/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: * [Get Webhook Post Fields](https://documentation.bamboohr.com/reference/get-post-fields) (`GET /api/v1/webhooks/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** * [Create Break Policy](https://documentation.bamboohr.com/reference/create-break-policy) (`POST /api/v1/time-tracking/break-policies`) * [Delete Break Policy](https://documentation.bamboohr.com/reference/delete-break-policy) (`DELETE /api/v1/time-tracking/break-policies/{id}`) * [Get Break Policy](https://documentation.bamboohr.com/reference/get-break-policy) (`GET /api/v1/time-tracking/break-policies/{id}`) * [List Break Policies](https://documentation.bamboohr.com/reference/list-break-policies) (`GET /api/v1/time-tracking/break-policies`) * [Sync Break Policy](https://documentation.bamboohr.com/reference/sync-break-policy) (`PUT /api/v1/time-tracking/break-policies/{id}/sync`) * [Update Break Policy](https://documentation.bamboohr.com/reference/update-break-policy) (`PATCH /api/v1/time-tracking/break-policies/{id}`) **Breaks within a policy** * [Create Break](https://documentation.bamboohr.com/reference/create-break) (`POST /api/v1/time-tracking/break-policies/{id}/breaks`) * [Delete Break](https://documentation.bamboohr.com/reference/delete-break) (`DELETE /api/v1/time-tracking/breaks/{id}`) * [Get Break](https://documentation.bamboohr.com/reference/get-break) (`GET /api/v1/time-tracking/breaks/{id}`) * [List Breaks for Break Policy](https://documentation.bamboohr.com/reference/list-break-policy-breaks) (`GET /api/v1/time-tracking/break-policies/{id}/breaks`) * [Replace Breaks for Break Policy](https://documentation.bamboohr.com/reference/replace-breaks-for-break-policy) (`PUT /api/v1/time-tracking/break-policies/{id}/breaks`) * [Update Break](https://documentation.bamboohr.com/reference/update-break) (`PATCH /api/v1/time-tracking/breaks/{id}`) **Policy assignments** * [Assign Employees to Break Policy](https://documentation.bamboohr.com/reference/assign-employees-to-break-policy) (`POST /api/v1/time-tracking/break-policies/{id}/assign`) * [List Break Policy Employees](https://documentation.bamboohr.com/reference/list-break-policy-employees) (`GET /api/v1/time-tracking/break-policies/{id}/employees`) * [List Employee Break Policies](https://documentation.bamboohr.com/reference/list-employee-break-policies) (`GET /api/v1/time-tracking/employees/{id}/break-policies`) * [Set Employees for Break Policy](https://documentation.bamboohr.com/reference/set-break-policy-employees) (`PUT /api/v1/time-tracking/break-policies/{id}/assign`) * [Unassign Employees from Break Policy](https://documentation.bamboohr.com/reference/unassign-employees-from-break-policy) (`POST /api/v1/time-tracking/break-policies/{id}/unassign`) **Employee availability and assessments** * [List Break Assessments](https://documentation.bamboohr.com/reference/list-break-assessments) (`GET /api/v1/time-tracking/break-assessments`) * [List Employee Break Availabilities](https://documentation.bamboohr.com/reference/list-employee-break-availabilities) (`GET /api/v1/time-tracking/employees/{id}/break-availabilities`) For an overview of how these endpoints fit together, see [Meal & Rest Breaks](https://documentation.bamboohr.com/reference/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](https://documentation.bamboohr.com/reference/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](https://documentation.bamboohr.com/reference/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](https://documentation.bamboohr.com/reference/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](https://documentation.bamboohr.com/reference/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: * [Get Field Options v1.2](https://documentation.bamboohr.com/reference/get-field-options-v1-2) (`POST /api/v1_2/datasets/{datasetName}/field-options`) This completes the Datasets v1.2 discovery workflow alongside: * [Get Fields from Dataset v1.2](https://documentation.bamboohr.com/reference/get-fields-from-dataset-v1-2), added December 11, 2025 * [List Datasets v1.2](https://documentation.bamboohr.com/reference/list-datasets-v1-2), added December 19, 2025 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: * [List Datasets v1.2](https://documentation.bamboohr.com/reference/list-datasets-v1-2) (`GET /api/v1_2/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: * [Get Fields from Dataset v1.2](https://documentation.bamboohr.com/reference/get-fields-from-dataset-v1-2) (`GET /api/v1_2/datasets/{datasetName}/fields`) 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: * [List Employees](https://documentation.bamboohr.com/reference/list-employees) (`GET /api/v1/employees`) 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: * [Get Countries](https://documentation.bamboohr.com/reference/get-countries-options) (`GET /api/v1/meta/countries/options`) * [List states and provinces for a country by Country ID](https://documentation.bamboohr.com/reference/get-states-by-country-id) (`GET /api/v1/meta/provinces/{countryId}`) 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: * [Get Goals Aggregate (v1.1)](https://documentation.bamboohr.com/reference/get-goals-aggregate-v1.1) (`GET /api/v1_1/performance/employees/{employeeId}/goals/aggregate`) * [Get Goals Aggregate (v1.2)](https://documentation.bamboohr.com/reference/get-goals-aggregate-v1.2) (`GET /api/v1_2/performance/employees/{employeeId}/goals/aggregate`) 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 , 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: * [Get Employee Photo](https://documentation.bamboohr.com/reference/get-employee-photo) (`GET /api/v1/employees/{employeeId}/photo/{size}`) 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](https://documentation.bamboohr.com/reference/request-custom-report-2/) 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](https://documentation.bamboohr.com/reference/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 | Parameters | Before 08/27/2019 | Today | | :--------------------------------------------------------------------------- | :---------------- | :------- | | **start** - Only show time off that occurs on/after the specified start date | Optional | Required | | **end** - Only show time off that occurs on/before the specified end date. | Optional | Required | ### Get Time Off Requests Documentation [https://documentation.bamboohr.com/reference/time-off-get-time-off-requests](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: . 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. 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://{companyDomain}.bamboohr.com/api/v1/employees/10001/tables/compensation` if your payload looks like this: ```html 2017-05-01 Year 10 ``` ...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: ```html 2017-05-01 ``` ...is just fine. IF, however, your payload looks like this: ```html 2017-05-01 Year ``` ...or like this... ```html 2017-05-01 10 ``` ...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. ## 2016.12 – Employment Status There are three fields used with these endpoints: with similar aliases in the API: 1. status 2. employmentStatus 3. employmentHistoryStatus There is also a table (used with these endpoints: 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} ```html 2016-08-01 ``` 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 ```html 2016-08-01 1234 ``` ## 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](https://documentation.bamboohr.com/reference/get-employees-directory-1). ## 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](https://documentation.bamboohr.com/reference/list-time-off-types).