Skip to content

BambooHR/bhr-api-python

BranchesTags

Repository files navigation

BambooHR Python SDK

Official Python SDK for the BambooHR API.

Overview

The BambooHR Python SDK provides a type-safe, Pythonic interface to the BambooHR REST API. It includes auto-generated client classes covering all public API endpoints, a fluent builder for authentication and configuration, and production-ready features such as automatic token refresh, retry with exponential backoff, and secure logging.

Requirements

  • Python 3.10+

Installation

pip install bamboohr-sdk

Quick Start

from bamboohr_sdk.client import BambooHRClient
from bamboohr_sdk.exceptions import ApiException

client = (
    BambooHRClient()
    .with_oauth("your-access-token")
    .for_company("your-company-subdomain")
    .build()
)

try:
    directory = client.employees().get_employees_directory()
    for emp in directory.employees or []:
        print(emp.get("displayName"))
except ApiException as e:
    print(f"API error ({e.status}): {e.reason}")

See GETTING_STARTED.md for a full walkthrough and AUTHENTICATION.md for all authentication options. OAuth 2.0 is recommended for all partner integrations — see the authentication guide for setup.

Documentation

SDK Features

Retry with Exponential Backoff

All API requests are automatically retried on transient failures (HTTP 408, 429, 504, 598). Configure via BambooHRClient:

client = (
    BambooHRClient()
    .with_oauth("your-access-token")
    .for_company("your-company")
    .with_retries(3)  # 0–5, default 1
    .build()
)

HTTPS Enforcement

All host URLs are automatically upgraded to HTTPS. Setting host="http://..." or host="example.com" will both resolve to https://....

Custom User-Agent

All requests include the header User-Agent: BHR-SDK/{version}/Python.

Request ID Support

Exceptions automatically extract the request ID from response headers (x-request-id, x-bamboohr-request-id, or request-id) for easier debugging:

try:
    api.some_endpoint()
except ApiException as e:
    print(e.request_id)  # Extracted from response headers

Secure Logging

The SDK uses Python's logging module under the bamboohr_sdk logger name. Sensitive headers (Authorization, API keys, cookies) and URL query parameters are automatically redacted in log output.

import logging
logging.getLogger("bamboohr_sdk").setLevel(logging.DEBUG)

Raw Response for Void Endpoints

Endpoints without a defined return type return an ApiResponse object instead of None, giving access to status code, headers, and raw response data.

API Endpoints

All URIs are relative to https://companySubDomain.bamboohr.com

Class Method HTTP request Description
AccountInformationApi call_5c5fb0f1211ae1c9451753f92f1053b6 GET /api/v1/meta/timezones List timezones
AccountInformationApi get_countries_options GET /api/v1/meta/countries/options Get Countries
AccountInformationApi get_states_by_country_id GET /api/v1/meta/provinces/{countryId} Get States by Country ID
AccountInformationApi list_fields GET /api/v1/meta/fields List Fields
AccountInformationApi list_list_fields GET /api/v1/meta/lists List List Fields
AccountInformationApi list_tabular_fields GET /api/v1/meta/tables List Tabular Fields
AccountInformationApi list_users GET /api/v1/meta/users List Users
AccountInformationApi update_list_field_values PUT /api/v1/meta/lists/{listFieldId} Update List Field Values
ApplicantTrackingApi create_application_comment POST /api/v1/applicant_tracking/applications/{applicationId}/comments Create Job Application Comment
ApplicantTrackingApi create_candidate POST /api/v1/applicant_tracking/application Create Candidate
ApplicantTrackingApi create_job_opening POST /api/v1/applicant_tracking/job_opening Create Job Opening
ApplicantTrackingApi get_application_details GET /api/v1/applicant_tracking/applications/{applicationId} Get Job Application Details
ApplicantTrackingApi get_applications GET /api/v1/applicant_tracking/applications Get Job Applications
ApplicantTrackingApi get_company_locations GET /api/v1/applicant_tracking/locations Get Company Locations
ApplicantTrackingApi get_hiring_leads GET /api/v1/applicant_tracking/hiring_leads Get Hiring Leads
ApplicantTrackingApi get_job_summaries GET /api/v1/applicant_tracking/jobs Get Job Summaries
ApplicantTrackingApi get_statuses GET /api/v1/applicant_tracking/statuses Get Applicant Statuses
ApplicantTrackingApi update_applicant_status POST /api/v1/applicant_tracking/applications/{applicationId}/status Update Applicant Status
BenefitsApi create_employee_dependent POST /api/v1/employeedependents Create Employee Dependent
BenefitsApi get_employee_dependent GET /api/v1/employeedependents/{id} Get Employee Dependent
BenefitsApi get_member_benefits GET /api/v1/benefits/member-benefits Get Member Benefits
BenefitsApi list_benefit_coverages GET /api/v1/benefitcoverages List Benefit Coverages
BenefitsApi list_benefit_deduction_types GET /api/v1/benefits/settings/deduction_types/all List Benefit Deduction Types
BenefitsApi list_company_benefits GET /api/v1/benefit/company_benefit List Company Benefits
BenefitsApi list_employee_benefits GET /api/v1/benefit/employee_benefit List Employee Benefits
BenefitsApi list_employee_dependents GET /api/v1/employeedependents List Employee Dependents
BenefitsApi list_member_benefit_events GET /api/v1/benefit/member_benefit List Member Benefit Events
BenefitsApi update_employee_dependent PUT /api/v1/employeedependents/{id} Update Employee Dependent
CompanyFilesApi add_company_file_category POST /api/v1/files/categories Create Company File Category
CompanyFilesApi delete_company_file DELETE /api/v1/files/{fileId} Delete Company File
CompanyFilesApi get_company_file GET /api/v1/files/{fileId} Get Company File
CompanyFilesApi list_company_files GET /api/v1/files/view Get Company Files and Categories
CompanyFilesApi update_company_file POST /api/v1/files/{fileId} Update Company File
CompanyFilesApi upload_company_file POST /api/v1/files Upload Company File
CompanyProfileApi get_company_profile_integrations GET /api/v1/company-profile-integrations Get Company Profile Integrations
CustomReportsApi get_by_report_id GET /api/v1/custom-reports/{reportId} Get Report by ID
CustomReportsApi list_reports GET /api/v1/custom-reports List Reports
DatasetsApi get_data_from_dataset POST /api/v1/datasets/{datasetName} Get Data from Dataset
DatasetsApi get_datasets GET /api/v1/datasets Get Datasets
DatasetsApi get_datasets_v12 GET /api/v1_2/datasets Get Datasets v1.2
DatasetsApi get_field_options POST /api/v1/datasets/{datasetName}/field-options Get Field Options
DatasetsApi get_field_options_v12 POST /api/v1_2/datasets/{datasetName}/field-options Get Field Options v1.2
DatasetsApi get_fields_from_dataset GET /api/v1/datasets/{datasetName}/fields Get Fields from Dataset
DatasetsApi get_fields_from_dataset_v12 GET /api/v1_2/datasets/{datasetName}/fields Get Fields from Dataset v1.2
EmployeeFilesApi add_employee_file_category POST /api/v1/employees/files/categories Create Employee File Category
EmployeeFilesApi delete_employee_file DELETE /api/v1/employees/{id}/files/{fileId} Delete Employee File
EmployeeFilesApi get_employee_file GET /api/v1/employees/{id}/files/{fileId} Get Employee File
EmployeeFilesApi list_employee_files GET /api/v1/employees/{id}/files/view List Employee Files
EmployeeFilesApi update_employee_file POST /api/v1/employees/{id}/files/{fileId} Update Employee File
EmployeeFilesApi upload_employee_file POST /api/v1/employees/{id}/files Upload Employee File
EmployeesApi create_employee POST /api/v1/employees Create Employee
EmployeesApi get_company_information GET /api/v1/company_information Get Company Information
EmployeesApi get_employee GET /api/v1/employees/{id} Get Employee
EmployeesApi get_employees_directory GET /api/v1/employees/directory Get Employee Directory
EmployeesApi list_employees GET /api/v1/employees List Employees
EmployeesApi update_employee POST /api/v1/employees/{id} Update Employee
GoalsApi delete_goal DELETE /api/v1/performance/employees/{employeeId}/goals/{goalId} Delete Goal
GoalsApi delete_goal_comment DELETE /api/v1/performance/employees/{employeeId}/goals/{goalId}/comments/{commentId} Delete Goal Comment
GoalsApi get_can_create_goal GET /api/v1/performance/employees/{employeeId}/goals/canCreateGoals Check Goal Creation Permission
GoalsApi get_goal_aggregate GET /api/v1/performance/employees/{employeeId}/goals/{goalId}/aggregate Get Goal Aggregate
GoalsApi get_goal_comments GET /api/v1/performance/employees/{employeeId}/goals/{goalId}/comments Get Goal Comments
GoalsApi get_goals GET /api/v1/performance/employees/{employeeId}/goals Get Goals
GoalsApi get_goals_aggregate_v1 GET /api/v1/performance/employees/{employeeId}/goals/aggregate Get Goals Aggregate
GoalsApi get_goals_aggregate_v1_1 GET /api/v1_1/performance/employees/{employeeId}/goals/aggregate Get Goals Aggregate v1.1
GoalsApi get_goals_aggregate_v1_2 GET /api/v1_2/performance/employees/{employeeId}/goals/aggregate Get Goals Aggregate v1.2
GoalsApi get_goals_alignment_options GET /api/v1/performance/employees/{employeeId}/goals/alignmentOptions Get Alignable Goal Options
GoalsApi get_goals_filters_v1 GET /api/v1/performance/employees/{employeeId}/goals/filters Get Goal Filters
GoalsApi get_goals_filters_v1_1 GET /api/v1_1/performance/employees/{employeeId}/goals/filters Get Goal Filters v1.1
GoalsApi get_goals_filters_v1_2 GET /api/v1_2/performance/employees/{employeeId}/goals/filters Get Goal Status Counts v1.2
GoalsApi get_goals_share_options GET /api/v1/performance/employees/{employeeId}/goals/shareOptions Get Available Goal Sharing Options
GoalsApi post_close_goal POST /api/v1/performance/employees/{employeeId}/goals/{goalId}/close Close Goal
GoalsApi post_goal POST /api/v1/performance/employees/{employeeId}/goals Create Goal
GoalsApi post_goal_comment POST /api/v1/performance/employees/{employeeId}/goals/{goalId}/comments Create Goal Comment
GoalsApi post_reopen_goal POST /api/v1/performance/employees/{employeeId}/goals/{goalId}/reopen Reopen Goal
GoalsApi put_goal_comment PUT /api/v1/performance/employees/{employeeId}/goals/{goalId}/comments/{commentId} Update Goal Comment
GoalsApi put_goal_milestone_progress PUT /api/v1/performance/employees/{employeeId}/goals/{goalId}/milestones/{milestoneId}/progress Update Milestone Progress
GoalsApi put_goal_progress PUT /api/v1/performance/employees/{employeeId}/goals/{goalId}/progress Update Goal Progress
GoalsApi put_goal_shared_with PUT /api/v1/performance/employees/{employeeId}/goals/{goalId}/sharedWith Update Goal Sharing
GoalsApi put_goal_v1 PUT /api/v1/performance/employees/{employeeId}/goals/{goalId} Update Goal
GoalsApi put_goal_v1_1 PUT /api/v1_1/performance/employees/{employeeId}/goals/{goalId} Update Goal v1.1
HoursApi create_or_update_time_tracking_hour_records POST /api/v1/timetracking/record Create or Update Hour Records
HoursApi create_time_tracking_hour_record POST /api/v1/timetracking/add Create Hour Record
HoursApi delete_time_tracking_hour_record DELETE /api/v1/timetracking/delete/{id} Delete Hour Record
HoursApi get_time_tracking_record GET /api/v1/timetracking/record/{id} Get Time Tracking Record
HoursApi update_time_tracking_record PUT /api/v1/timetracking/adjust Update Hour Record
LastChangeInformationApi get_changed_employee_ids GET /api/v1/employees/changed Get Changed Employee IDs
LoginApi login POST /api/v1/login Login
PhotosApi get_employee_photo GET /api/v1/employees/{employeeId}/photo/{size} Get Employee Photo
PhotosApi upload_employee_photo POST /api/v1/employees/{employeeId}/photo Upload Employee Photo
PublicAPIApi add_company_file_category POST /api/v1/files/categories Create Company File Category
PublicAPIApi add_employee_file_category POST /api/v1/employees/files/categories Create Employee File Category
PublicAPIApi adjust_time_off_balance PUT /api/v1/employees/{employeeId}/time_off/balance_adjustment Adjust Time Off Balance
PublicAPIApi assign_employees_to_break_policy POST /api/v1/time-tracking/break-policies/{id}/assign Assign Employees to Break Policy
PublicAPIApi assign_time_off_policies PUT /api/v1/employees/{employeeId}/time_off/policies Assign Time Off Policies
PublicAPIApi assign_time_off_policies_v1_1 PUT /api/v1_1/employees/{employeeId}/time_off/policies Assign Time Off Policies v1.1
PublicAPIApi call_5c5fb0f1211ae1c9451753f92f1053b6 GET /api/v1/meta/timezones List timezones
PublicAPIApi create_application_comment POST /api/v1/applicant_tracking/applications/{applicationId}/comments Create Job Application Comment
PublicAPIApi create_break POST /api/v1/time-tracking/break-policies/{id}/breaks Create Break
PublicAPIApi create_break_policy POST /api/v1/time-tracking/break-policies Create Break Policy
PublicAPIApi create_candidate POST /api/v1/applicant_tracking/application Create Candidate
PublicAPIApi create_employee POST /api/v1/employees Create Employee
PublicAPIApi create_employee_dependent POST /api/v1/employeedependents Create Employee Dependent
PublicAPIApi create_employee_training_record POST /api/v1/training/record/employee/{employeeId} Create Employee Training Record
PublicAPIApi create_job_opening POST /api/v1/applicant_tracking/job_opening Create Job Opening
PublicAPIApi create_or_update_time_tracking_hour_records POST /api/v1/timetracking/record Create or Update Hour Records
PublicAPIApi create_or_update_timesheet_clock_entries POST /api/v1/time_tracking/clock_entries/store Create or Update Timesheet Clock Entries
PublicAPIApi create_or_update_timesheet_hour_entries POST /api/v1/time_tracking/hour_entries/store Create or Update Timesheet Hour Entries
PublicAPIApi create_table_row POST /api/v1/employees/{id}/tables/{table} Create Table Row
PublicAPIApi create_table_row_v11 POST /api/v1_1/employees/{id}/tables/{table} Create Table Row v1.1
PublicAPIApi create_time_off_history PUT /api/v1/employees/{employeeId}/time_off/history Create Time Off History Item
PublicAPIApi create_time_off_request PUT /api/v1/employees/{employeeId}/time_off/request Create Time Off Request
PublicAPIApi create_time_tracking_hour_record POST /api/v1/timetracking/add Create Hour Record
PublicAPIApi create_time_tracking_project POST /api/v1/time_tracking/projects Create Time Tracking Project
PublicAPIApi create_timesheet_clock_in_entry POST /api/v1/time_tracking/employees/{employeeId}/clock_in Create Timesheet Clock-In Entry
PublicAPIApi create_timesheet_clock_out_entry POST /api/v1/time_tracking/employees/{employeeId}/clock_out Create Timesheet Clock-Out Entry
PublicAPIApi create_training_category POST /api/v1/training/category Create Training Category
PublicAPIApi create_training_type POST /api/v1/training/type Create Training Type
PublicAPIApi create_webhook POST /api/v1/webhooks Create Webhook
PublicAPIApi delete_break DELETE /api/v1/time-tracking/breaks/{id} Delete Break
PublicAPIApi delete_break_policy DELETE /api/v1/time-tracking/break-policies/{id} Delete Break Policy
PublicAPIApi delete_company_file DELETE /api/v1/files/{fileId} Delete Company File
PublicAPIApi delete_employee_file DELETE /api/v1/employees/{id}/files/{fileId} Delete Employee File
PublicAPIApi delete_employee_table_row DELETE /api/v1/employees/{id}/tables/{table}/{rowId} Delete Employee Table Row
PublicAPIApi delete_employee_training_record DELETE /api/v1/training/record/{employeeTrainingRecordId} Delete Employee Training Record
PublicAPIApi delete_goal DELETE /api/v1/performance/employees/{employeeId}/goals/{goalId} Delete Goal
PublicAPIApi delete_goal_comment DELETE /api/v1/performance/employees/{employeeId}/goals/{goalId}/comments/{commentId} Delete Goal Comment
PublicAPIApi delete_time_tracking_hour_record DELETE /api/v1/timetracking/delete/{id} Delete Hour Record
PublicAPIApi delete_timesheet_clock_entries_via_post POST /api/v1/time_tracking/clock_entries/delete Delete Timesheet Clock Entries
PublicAPIApi delete_timesheet_hour_entries_via_post POST /api/v1/time_tracking/hour_entries/delete Delete Timesheet Hour Entries
PublicAPIApi delete_training_category DELETE /api/v1/training/category/{trainingCategoryId} Delete Training Category
PublicAPIApi delete_training_type DELETE /api/v1/training/type/{trainingTypeId} Delete Training Type
PublicAPIApi delete_webhook DELETE /api/v1/webhooks/{id} Delete Webhook
PublicAPIApi get_application_details GET /api/v1/applicant_tracking/applications/{applicationId} Get Job Application Details
PublicAPIApi get_applications GET /api/v1/applicant_tracking/applications Get Job Applications
PublicAPIApi get_break GET /api/v1/time-tracking/breaks/{id} Get Break
PublicAPIApi get_break_policy GET /api/v1/time-tracking/break-policies/{id} Get Break Policy
PublicAPIApi get_by_report_id GET /api/v1/custom-reports/{reportId} Get Report by ID
PublicAPIApi get_can_create_goal GET /api/v1/performance/employees/{employeeId}/goals/canCreateGoals Check Goal Creation Permission
PublicAPIApi get_changed_employee_ids GET /api/v1/employees/changed Get Changed Employee IDs
PublicAPIApi get_changed_employee_table_data GET /api/v1/employees/changed/tables/{table} Get Changed Employee Table Data
PublicAPIApi get_company_file GET /api/v1/files/{fileId} Get Company File
PublicAPIApi get_company_information GET /api/v1/company_information Get Company Information
PublicAPIApi get_company_locations GET /api/v1/applicant_tracking/locations Get Company Locations
PublicAPIApi get_company_profile_integrations GET /api/v1/company-profile-integrations Get Company Profile Integrations
PublicAPIApi get_company_report GET /api/v1/reports/{id} Get Company Report
PublicAPIApi get_countries_options GET /api/v1/meta/countries/options Get Countries
PublicAPIApi get_data_from_dataset POST /api/v1/datasets/{datasetName} Get Data from Dataset
PublicAPIApi get_datasets GET /api/v1/datasets Get Datasets
PublicAPIApi get_datasets_v12 GET /api/v1_2/datasets Get Datasets v1.2
PublicAPIApi get_employee GET /api/v1/employees/{id} Get Employee
PublicAPIApi get_employee_dependent GET /api/v1/employeedependents/{id} Get Employee Dependent
PublicAPIApi get_employee_file GET /api/v1/employees/{id}/files/{fileId} Get Employee File
PublicAPIApi get_employee_photo GET /api/v1/employees/{employeeId}/photo/{size} Get Employee Photo
PublicAPIApi get_employee_table_data GET /api/v1/employees/{id}/tables/{table} Get Employee Table Data
PublicAPIApi get_employees_directory GET /api/v1/employees/directory Get Employee Directory
PublicAPIApi get_field_options POST /api/v1/datasets/{datasetName}/field-options Get Field Options
PublicAPIApi get_field_options_v12 POST /api/v1_2/datasets/{datasetName}/field-options Get Field Options v1.2
PublicAPIApi get_fields_from_dataset GET /api/v1/datasets/{datasetName}/fields Get Fields from Dataset
PublicAPIApi get_fields_from_dataset_v12 GET /api/v1_2/datasets/{datasetName}/fields Get Fields from Dataset v1.2
PublicAPIApi get_goal_aggregate GET /api/v1/performance/employees/{employeeId}/goals/{goalId}/aggregate Get Goal Aggregate
PublicAPIApi get_goal_comments GET /api/v1/performance/employees/{employeeId}/goals/{goalId}/comments Get Goal Comments
PublicAPIApi get_goals GET /api/v1/performance/employees/{employeeId}/goals Get Goals
PublicAPIApi get_goals_aggregate_v1 GET /api/v1/performance/employees/{employeeId}/goals/aggregate Get Goals Aggregate
PublicAPIApi get_goals_aggregate_v1_1 GET /api/v1_1/performance/employees/{employeeId}/goals/aggregate Get Goals Aggregate v1.1
PublicAPIApi get_goals_aggregate_v1_2 GET /api/v1_2/performance/employees/{employeeId}/goals/aggregate Get Goals Aggregate v1.2
PublicAPIApi get_goals_alignment_options GET /api/v1/performance/employees/{employeeId}/goals/alignmentOptions Get Alignable Goal Options
PublicAPIApi get_goals_filters_v1 GET /api/v1/performance/employees/{employeeId}/goals/filters Get Goal Filters
PublicAPIApi get_goals_filters_v1_1 GET /api/v1_1/performance/employees/{employeeId}/goals/filters Get Goal Filters v1.1
PublicAPIApi get_goals_filters_v1_2 GET /api/v1_2/performance/employees/{employeeId}/goals/filters Get Goal Status Counts v1.2
PublicAPIApi get_goals_share_options GET /api/v1/performance/employees/{employeeId}/goals/shareOptions Get Available Goal Sharing Options
PublicAPIApi get_hiring_leads GET /api/v1/applicant_tracking/hiring_leads Get Hiring Leads
PublicAPIApi get_job_summaries GET /api/v1/applicant_tracking/jobs Get Job Summaries
PublicAPIApi get_member_benefits GET /api/v1/benefits/member-benefits Get Member Benefits
PublicAPIApi get_monitor_fields GET /api/v1/webhooks/monitor_fields Get Monitor Fields
PublicAPIApi get_post_fields GET /api/v1/webhooks/post-fields Get Post Fields
PublicAPIApi get_states_by_country_id GET /api/v1/meta/provinces/{countryId} Get States by Country ID
PublicAPIApi get_statuses GET /api/v1/applicant_tracking/statuses Get Applicant Statuses
PublicAPIApi get_time_off_balance GET /api/v1/employees/{employeeId}/time_off/calculator Get Time Off Balance
PublicAPIApi get_time_tracking_record GET /api/v1/timetracking/record/{id} Get Time Tracking Record
PublicAPIApi get_webhook GET /api/v1/webhooks/{id} Get Webhook
PublicAPIApi get_webhook_logs GET /api/v1/webhooks/{id}/log Get Webhook Logs
PublicAPIApi list_benefit_coverages GET /api/v1/benefitcoverages List Benefit Coverages
PublicAPIApi list_benefit_deduction_types GET /api/v1/benefits/settings/deduction_types/all List Benefit Deduction Types
PublicAPIApi list_break_assessments GET /api/v1/time-tracking/break-assessments List Break Assessments
PublicAPIApi list_break_policies GET /api/v1/time-tracking/break-policies List Break Policies
PublicAPIApi list_break_policy_breaks GET /api/v1/time-tracking/break-policies/{id}/breaks List Breaks for Break Policy
PublicAPIApi list_break_policy_employees GET /api/v1/time-tracking/break-policies/{id}/employees List Break Policy Employees
PublicAPIApi list_company_benefits GET /api/v1/benefit/company_benefit List Company Benefits
PublicAPIApi list_company_files GET /api/v1/files/view Get Company Files and Categories
PublicAPIApi list_employee_benefits GET /api/v1/benefit/employee_benefit List Employee Benefits
PublicAPIApi list_employee_break_availabilities GET /api/v1/time-tracking/employees/{id}/break-availabilities List Employee Break Availabilities
PublicAPIApi list_employee_break_policies GET /api/v1/time-tracking/employees/{id}/break-policies List Employee Break Policies
PublicAPIApi list_employee_dependents GET /api/v1/employeedependents List Employee Dependents
PublicAPIApi list_employee_files GET /api/v1/employees/{id}/files/view List Employee Files
PublicAPIApi list_employee_time_off_policies GET /api/v1/employees/{employeeId}/time_off/policies List Employee Time Off Policies
PublicAPIApi list_employee_time_off_policies_v1_1 GET /api/v1_1/employees/{employeeId}/time_off/policies List Employee Time Off Policies v1.1
PublicAPIApi list_employee_trainings GET /api/v1/training/record/employee/{employeeId} List Employee Training Records
PublicAPIApi list_employees GET /api/v1/employees List Employees
PublicAPIApi list_fields GET /api/v1/meta/fields List Fields
PublicAPIApi list_list_fields GET /api/v1/meta/lists List List Fields
PublicAPIApi list_member_benefit_events GET /api/v1/benefit/member_benefit List Member Benefit Events
PublicAPIApi list_reports GET /api/v1/custom-reports List Reports
PublicAPIApi list_tabular_fields GET /api/v1/meta/tables List Tabular Fields
PublicAPIApi list_time_off_policies GET /api/v1/meta/time_off/policies List Time Off Policies
PublicAPIApi list_time_off_requests GET /api/v1/time_off/requests List Time Off Requests
PublicAPIApi list_time_off_types GET /api/v1/meta/time_off/types List Time Off Types
PublicAPIApi list_timesheet_entries GET /api/v1/time_tracking/timesheet_entries List Timesheet Entries
PublicAPIApi list_training_categories GET /api/v1/training/category List Training Categories
PublicAPIApi list_training_types GET /api/v1/training/type List Training Types
PublicAPIApi list_users GET /api/v1/meta/users List Users
PublicAPIApi list_webhooks GET /api/v1/webhooks List Webhooks
PublicAPIApi list_whos_out GET /api/v1/time_off/whos_out List Who’s Out
PublicAPIApi login POST /api/v1/login Login
PublicAPIApi post_close_goal POST /api/v1/performance/employees/{employeeId}/goals/{goalId}/close Close Goal
PublicAPIApi post_goal POST /api/v1/performance/employees/{employeeId}/goals Create Goal
PublicAPIApi post_goal_comment POST /api/v1/performance/employees/{employeeId}/goals/{goalId}/comments Create Goal Comment
PublicAPIApi post_reopen_goal POST /api/v1/performance/employees/{employeeId}/goals/{goalId}/reopen Reopen Goal
PublicAPIApi put_goal_comment PUT /api/v1/performance/employees/{employeeId}/goals/{goalId}/comments/{commentId} Update Goal Comment
PublicAPIApi put_goal_milestone_progress PUT /api/v1/performance/employees/{employeeId}/goals/{goalId}/milestones/{milestoneId}/progress Update Milestone Progress
PublicAPIApi put_goal_progress PUT /api/v1/performance/employees/{employeeId}/goals/{goalId}/progress Update Goal Progress
PublicAPIApi put_goal_shared_with PUT /api/v1/performance/employees/{employeeId}/goals/{goalId}/sharedWith Update Goal Sharing
PublicAPIApi put_goal_v1 PUT /api/v1/performance/employees/{employeeId}/goals/{goalId} Update Goal
PublicAPIApi put_goal_v1_1 PUT /api/v1_1/performance/employees/{employeeId}/goals/{goalId} Update Goal v1.1
PublicAPIApi replace_breaks_for_break_policy PUT /api/v1/time-tracking/break-policies/{id}/breaks Replace Breaks for Break Policy
PublicAPIApi request_custom_report POST /api/v1/reports/custom Request Custom Report
PublicAPIApi set_break_policy_employees PUT /api/v1/time-tracking/break-policies/{id}/assign Set Employees for Break Policy
PublicAPIApi sync_break_policy PUT /api/v1/time-tracking/break-policies/{id}/sync Sync Break Policy
PublicAPIApi unassign_employees_from_break_policy POST /api/v1/time-tracking/break-policies/{id}/unassign Unassign Employees from Break Policy
PublicAPIApi update_applicant_status POST /api/v1/applicant_tracking/applications/{applicationId}/status Update Applicant Status
PublicAPIApi update_break PATCH /api/v1/time-tracking/breaks/{id} Update Break
PublicAPIApi update_break_policy PATCH /api/v1/time-tracking/break-policies/{id} Update Break Policy
PublicAPIApi update_company_file POST /api/v1/files/{fileId} Update Company File
PublicAPIApi update_employee POST /api/v1/employees/{id} Update Employee
PublicAPIApi update_employee_dependent PUT /api/v1/employeedependents/{id} Update Employee Dependent
PublicAPIApi update_employee_file POST /api/v1/employees/{id}/files/{fileId} Update Employee File
PublicAPIApi update_employee_training_record PUT /api/v1/training/record/{employeeTrainingRecordId} Update Employee Training Record
PublicAPIApi update_list_field_values PUT /api/v1/meta/lists/{listFieldId} Update List Field Values
PublicAPIApi update_table_row POST /api/v1/employees/{id}/tables/{table}/{rowId} Update Table Row
PublicAPIApi update_table_row_v11 POST /api/v1_1/employees/{id}/tables/{table}/{rowId} Update Table Row v1.1
PublicAPIApi update_time_off_request_status PUT /api/v1/time_off/requests/{requestId}/status Update Time Off Request Status
PublicAPIApi update_time_tracking_record PUT /api/v1/timetracking/adjust Update Hour Record
PublicAPIApi update_training_category PUT /api/v1/training/category/{trainingCategoryId} Update Training Category
PublicAPIApi update_training_type PUT /api/v1/training/type/{trainingTypeId} Update Training Type
PublicAPIApi update_webhook PUT /api/v1/webhooks/{id} Update Webhook
PublicAPIApi upload_company_file POST /api/v1/files Upload Company File
PublicAPIApi upload_employee_file POST /api/v1/employees/{id}/files Upload Employee File
PublicAPIApi upload_employee_photo POST /api/v1/employees/{employeeId}/photo Upload Employee Photo
ReportsApi get_company_report GET /api/v1/reports/{id} Get Company Report
ReportsApi request_custom_report POST /api/v1/reports/custom Request Custom Report
TabularDataApi create_table_row POST /api/v1/employees/{id}/tables/{table} Create Table Row
TabularDataApi create_table_row_v11 POST /api/v1_1/employees/{id}/tables/{table} Create Table Row v1.1
TabularDataApi delete_employee_table_row DELETE /api/v1/employees/{id}/tables/{table}/{rowId} Delete Employee Table Row
TabularDataApi get_changed_employee_table_data GET /api/v1/employees/changed/tables/{table} Get Changed Employee Table Data
TabularDataApi get_employee_table_data GET /api/v1/employees/{id}/tables/{table} Get Employee Table Data
TabularDataApi update_table_row POST /api/v1/employees/{id}/tables/{table}/{rowId} Update Table Row
TabularDataApi update_table_row_v11 POST /api/v1_1/employees/{id}/tables/{table}/{rowId} Update Table Row v1.1
TimeOffApi adjust_time_off_balance PUT /api/v1/employees/{employeeId}/time_off/balance_adjustment Adjust Time Off Balance
TimeOffApi assign_time_off_policies PUT /api/v1/employees/{employeeId}/time_off/policies Assign Time Off Policies
TimeOffApi assign_time_off_policies_v1_1 PUT /api/v1_1/employees/{employeeId}/time_off/policies Assign Time Off Policies v1.1
TimeOffApi create_time_off_history PUT /api/v1/employees/{employeeId}/time_off/history Create Time Off History Item
TimeOffApi create_time_off_request PUT /api/v1/employees/{employeeId}/time_off/request Create Time Off Request
TimeOffApi get_time_off_balance GET /api/v1/employees/{employeeId}/time_off/calculator Get Time Off Balance
TimeOffApi list_employee_time_off_policies GET /api/v1/employees/{employeeId}/time_off/policies List Employee Time Off Policies
TimeOffApi list_employee_time_off_policies_v1_1 GET /api/v1_1/employees/{employeeId}/time_off/policies List Employee Time Off Policies v1.1
TimeOffApi list_time_off_policies GET /api/v1/meta/time_off/policies List Time Off Policies
TimeOffApi list_time_off_requests GET /api/v1/time_off/requests List Time Off Requests
TimeOffApi list_time_off_types GET /api/v1/meta/time_off/types List Time Off Types
TimeOffApi list_whos_out GET /api/v1/time_off/whos_out List Who’s Out
TimeOffApi update_time_off_request_status PUT /api/v1/time_off/requests/{requestId}/status Update Time Off Request Status
TimeTrackingApi assign_employees_to_break_policy POST /api/v1/time-tracking/break-policies/{id}/assign Assign Employees to Break Policy
TimeTrackingApi create_break POST /api/v1/time-tracking/break-policies/{id}/breaks Create Break
TimeTrackingApi create_break_policy POST /api/v1/time-tracking/break-policies Create Break Policy
TimeTrackingApi create_or_update_timesheet_clock_entries POST /api/v1/time_tracking/clock_entries/store Create or Update Timesheet Clock Entries
TimeTrackingApi create_or_update_timesheet_hour_entries POST /api/v1/time_tracking/hour_entries/store Create or Update Timesheet Hour Entries
TimeTrackingApi create_time_tracking_project POST /api/v1/time_tracking/projects Create Time Tracking Project
TimeTrackingApi create_timesheet_clock_in_entry POST /api/v1/time_tracking/employees/{employeeId}/clock_in Create Timesheet Clock-In Entry
TimeTrackingApi create_timesheet_clock_out_entry POST /api/v1/time_tracking/employees/{employeeId}/clock_out Create Timesheet Clock-Out Entry
TimeTrackingApi delete_break DELETE /api/v1/time-tracking/breaks/{id} Delete Break
TimeTrackingApi delete_break_policy DELETE /api/v1/time-tracking/break-policies/{id} Delete Break Policy
TimeTrackingApi delete_timesheet_clock_entries_via_post POST /api/v1/time_tracking/clock_entries/delete Delete Timesheet Clock Entries
TimeTrackingApi delete_timesheet_hour_entries_via_post POST /api/v1/time_tracking/hour_entries/delete Delete Timesheet Hour Entries
TimeTrackingApi get_break GET /api/v1/time-tracking/breaks/{id} Get Break
TimeTrackingApi get_break_policy GET /api/v1/time-tracking/break-policies/{id} Get Break Policy
TimeTrackingApi list_break_assessments GET /api/v1/time-tracking/break-assessments List Break Assessments
TimeTrackingApi list_break_policies GET /api/v1/time-tracking/break-policies List Break Policies
TimeTrackingApi list_break_policy_breaks GET /api/v1/time-tracking/break-policies/{id}/breaks List Breaks for Break Policy
TimeTrackingApi list_break_policy_employees GET /api/v1/time-tracking/break-policies/{id}/employees List Break Policy Employees
TimeTrackingApi list_employee_break_availabilities GET /api/v1/time-tracking/employees/{id}/break-availabilities List Employee Break Availabilities
TimeTrackingApi list_employee_break_policies GET /api/v1/time-tracking/employees/{id}/break-policies List Employee Break Policies
TimeTrackingApi list_timesheet_entries GET /api/v1/time_tracking/timesheet_entries List Timesheet Entries
TimeTrackingApi replace_breaks_for_break_policy PUT /api/v1/time-tracking/break-policies/{id}/breaks Replace Breaks for Break Policy
TimeTrackingApi set_break_policy_employees PUT /api/v1/time-tracking/break-policies/{id}/assign Set Employees for Break Policy
TimeTrackingApi sync_break_policy PUT /api/v1/time-tracking/break-policies/{id}/sync Sync Break Policy
TimeTrackingApi unassign_employees_from_break_policy POST /api/v1/time-tracking/break-policies/{id}/unassign Unassign Employees from Break Policy
TimeTrackingApi update_break PATCH /api/v1/time-tracking/breaks/{id} Update Break
TimeTrackingApi update_break_policy PATCH /api/v1/time-tracking/break-policies/{id} Update Break Policy
TrainingApi create_employee_training_record POST /api/v1/training/record/employee/{employeeId} Create Employee Training Record
TrainingApi create_training_category POST /api/v1/training/category Create Training Category
TrainingApi create_training_type POST /api/v1/training/type Create Training Type
TrainingApi delete_employee_training_record DELETE /api/v1/training/record/{employeeTrainingRecordId} Delete Employee Training Record
TrainingApi delete_training_category DELETE /api/v1/training/category/{trainingCategoryId} Delete Training Category
TrainingApi delete_training_type DELETE /api/v1/training/type/{trainingTypeId} Delete Training Type
TrainingApi list_employee_trainings GET /api/v1/training/record/employee/{employeeId} List Employee Training Records
TrainingApi list_training_categories GET /api/v1/training/category List Training Categories
TrainingApi list_training_types GET /api/v1/training/type List Training Types
TrainingApi update_employee_training_record PUT /api/v1/training/record/{employeeTrainingRecordId} Update Employee Training Record
TrainingApi update_training_category PUT /api/v1/training/category/{trainingCategoryId} Update Training Category
TrainingApi update_training_type PUT /api/v1/training/type/{trainingTypeId} Update Training Type
WebhooksApi create_webhook POST /api/v1/webhooks Create Webhook
WebhooksApi delete_webhook DELETE /api/v1/webhooks/{id} Delete Webhook
WebhooksApi get_monitor_fields GET /api/v1/webhooks/monitor_fields Get Monitor Fields
WebhooksApi get_post_fields GET /api/v1/webhooks/post-fields Get Post Fields
WebhooksApi get_webhook GET /api/v1/webhooks/{id} Get Webhook
WebhooksApi get_webhook_logs GET /api/v1/webhooks/{id}/log Get Webhook Logs
WebhooksApi list_webhooks GET /api/v1/webhooks List Webhooks
WebhooksApi update_webhook PUT /api/v1/webhooks/{id} Update Webhook

Models

Exceptions

  • Exceptions - Information about exceptions, potential causes, and debugging tips

Troubleshooting

Common Errors

Authentication Errors (401)

Symptom: AuthenticationFailedException on every request.

Solutions:

  • API key: Verify your key is correct and not disabled. The SDK sends it as HTTP Basic auth with "x" as the password — this is handled automatically.
  • OAuth: Check that your access token hasn't expired. Use with_oauth_refresh() for automatic token renewal.
  • Company subdomain: Ensure for_company() matches your BambooHR subdomain exactly (e.g., if your URL is acme.bamboohr.com, use "acme").

Permission Errors (403)

Symptom: PermissionDeniedException for specific endpoints.

Solutions:

  • Verify the API key or OAuth token has access to the requested resource.
  • Contact your BambooHR administrator to review API access permissions.
  • Check if IP restrictions are in place for API access.

Rate Limiting (429)

Symptom: RateLimitExceededException during batch operations.

Solutions:

  • The SDK automatically retries on 429 responses with exponential backoff. Increase retries: 
    client = BambooHRClient().with_retries(5).for_company("acme").build()
  • Add delays between batch requests: time.sleep(0.1) between calls.
  • Check the Retry-After response header for server guidance.

Network Troubleshooting

Connection Timeouts

Symptom: Requests hang or fail with timeout errors.

Solutions:

  • Configure a timeout: 
    client = BambooHRClient().with_timeout(30.0).for_company("acme").build()
  • Check your network connection and firewall settings.
  • Verify that *.bamboohr.com is accessible from your network.

SSL/TLS Errors

Symptom: SSL certificate verification failures.

Solutions:

  • Ensure your Python installation has up-to-date CA certificates: pip install --upgrade certifi
  • If behind a corporate proxy, your IT team may need to add the proxy's CA certificate to your trust store.
  • Do not disable SSL verification in production.

Proxy Configuration

If you're behind a corporate proxy, configure it via environment variables:

export HTTPS_PROXY=https://proxy.example.com:8080

Enabling Debug Logging

Enable detailed request/response logging to diagnose issues:

import logging
logging.basicConfig(level=logging.DEBUG)
logging.getLogger("bamboohr_sdk").setLevel(logging.DEBUG)

This will log request URLs, response status codes, retry attempts, and token refresh events. Sensitive data (API keys, tokens, Authorization headers) is automatically redacted.

Getting Help

When reporting issues, include:

  • The request ID from the exception (e.request_id) — this helps BambooHR support trace the request.
  • The HTTP status code and error message.
  • The SDK version (pip show bamboohr-sdk).
  • Debug log output (sensitive data is auto-redacted).

Project Structure

bhr-api-python/
├── bamboohr_sdk/               # Main package
│   ├── api/                    # Auto-generated API classes
│   ├── models/                 # Auto-generated data models
│   ├── client/                 # Custom API client & auth
│   │   ├── auth/               # TokenManager, RefreshProvider
│   │   ├── middleware/         # OAuth2, RequestId middleware
│   │   └── logger/             # SecureLogger
│   ├── api_helper.py           # Retry logic & logging utilities
│   └── api_error_helper.py     # Error catalog & exception factory
├── test/                       # Auto-generated API test stubs
├── tests/                      # Custom hand-written tests
├── docs/                       # Auto-generated API documentation
├── templates-python/           # Custom openapi-generator templates
├── scripts/                    # Post-generation scripts
├── examples/                   # Usage examples
└── pyproject.toml              # Project configuration

Development Setup

# Clone the repository
git clone https://github.com/BambooHR/bhr-api-python.git
cd bhr-api-python

# Create a virtual environment
python -m venv .venv
source .venv/bin/activate

# Install with dev dependencies
pip install -e ".[dev]"

Linting & Formatting

# Check linting
ruff check bamboohr_sdk/ tests/

# Auto-fix linting issues
ruff check --fix bamboohr_sdk/ tests/

# Format code
ruff format bamboohr_sdk/ tests/

Type Checking

mypy bamboohr_sdk/

Testing

pytest

Protecting Implemented Tests

The test/ directory contains auto-generated API test stubs created by make generate. These stubs are overwritten on each regeneration. Once you implement real test logic in a test file, add it to .openapi-generator-ignore to prevent it from being overwritten:

# .openapi-generator-ignore
test/test_employees_api.py
test/test_time_tracking_api.py

This ensures your implemented tests survive regeneration while new API test stubs are still generated for any newly added APIs.

Generating the SDK

This requires access to the internal BambooHR OpenAPI spec. The path to the spec file is specified by the OPENAPI_SPEC_PATH environment variable.

make generate

Manual changes to the auto-generated code

If you need to make manual changes to the auto-generated code, update the corresponding template in the templates-python directory and run make generate to regenerate the SDK. We have customized several templates to add SDK-specific features.

The following templates in templates-python/ have been modified from the OpenAPI Generator defaults:

Template Modifications Rationale
api.mustache Custom retry logic, secure logging, request ID extraction, void endpoint handling Production-ready API calls with automatic retries and debugging support
api_client.mustache HTTPS enforcement, custom User-Agent header, middleware pipeline Security (HTTPS-only) and observability (request tracing)
configuration.mustache HTTPS URL enforcement, retry configuration, custom defaults Prevent accidental plaintext HTTP, sane retry defaults
exceptions.mustache Status-specific exception hierarchy, potential_causes()/debugging_tips() methods, request ID support Developer-friendly error handling with built-in troubleshooting
README.mustache Complete custom README with troubleshooting and manual change tracking Developer experience and onboarding
api_test.mustache Test stub customizations Consistent test structure

Nearly all files under bamboohr_sdk/api/, bamboohr_sdk/models/, test/, and docs/ are generated by the make generate command, with the following exceptions protected via .openapi-generator-ignore:

File/Directory Purpose Why it's protected
bamboohr_sdk/client/ Fluent API client, auth builder, token manager, OAuth2 middleware, secure logger Core SDK experience — all auth, retry, and logging logic lives here
bamboohr_sdk/api_helper.py Retry logic with exponential backoff, secure request/response logging Heavily customized from generator default — handles retry strategy and log redaction
bamboohr_sdk/api_error_helper.py Error catalog mapping HTTP status codes to exception classes with causes/tips Hand-written error metadata — regenerate exception classes via scripts/generate_exceptions.py
bamboohr_sdk/api/manual_api.py Hand-written API class for endpoints not covered by the OpenAPI spec Supplements auto-generated APIs
tests/ Hand-written unit and integration tests Protected separately from auto-generated test/ stubs
examples/ Usage examples and getting started code Documentation — not generated

Custom descriptions for some API docs are added in the scripts/post_generate.py script, which is run as part of the make generate command.

Note: regeneration will not force an overwrite of tests in the test/ directory, unless tests are deleted first.

Generating Error Documentation

The error documentation is automatically generated from the error messages defined in api_error_helper.py. To update the documentation when error messages are added or modified, run:

make generate-error-docs

Note that this script will also run as part of the make generate command.

This will:

  1. Regenerate exception classes in bamboohr_sdk/exceptions.py
  2. Regenerate the docs/Exceptions/Exceptions.md file with the latest error information
  3. Generate exception documentation in docs/Exceptions/Classes/

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

Data Handling

This SDK is a thin HTTP client for the BambooHR API. All data transits directly between your application and the BambooHR API over HTTPS — the SDK does not send telemetry, analytics, or data to any other destination.

  • Authentication: API keys and OAuth tokens are sent in request headers to https://{subdomain}.bamboohr.com. Credentials are automatically redacted from debug log output.
  • API data: Requests and responses may include HR data such as employee records, payroll, time off, benefits, and related information. See the API documentation for details on specific endpoints and data types.
  • Logging: The SDK's debug logger redacts sensitive headers (Authorization, API keys) by default. No request or response bodies are logged unless you explicitly enable verbose logging in your application.

Support

If you encounter any issues or need assistance with this SDK, please contact us through one of these channels:

About this package

This Python package is automatically generated by the OpenAPI Generator project:

  • API version: 1.0
  • Package version: 1.0.0
  • Generator version: 7.16.0
  • Build package: org.openapitools.codegen.languages.PythonClientCodegen

Terms

Use of the BambooHR API is subject to the BambooHR Developer Terms of Service.

License

MIT

About

Python wrapper for the BambooHR API

Resources

Readme

License

MIT license

Contributing

Contributing
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages