Table of Contents
Imagine having the ability to manage all your HR needs—employee data, leave tracking, job postings—right at your fingertips. The BambooHR API makes this a reality, allowing you to automate routine HR tasks and easily integrate BambooHR with your existing systems. From employee onboarding to payroll syncing, the BambooHR API does it all, so you can focus on what really matters: your people.
In this directory, we’ll walk you through everything you need to know about the BambooHR API. We’ll explore its key features, discuss best practices for securing your API integration, go over the most commonly used API endpoints, and dive into real-world use cases where BambooHR’s power is unleashed. To top it off, we’ll troubleshoot some common pitfalls to ensure your integration is smooth sailing.
Key Features and Capabilities
BambooHR’s API is packed with features to help you get the most out of your HR management system. Here’s a peek at what it can do:
- Employee Data at Your Fingertips: Access and manage employee profiles, job roles, departments, and even custom fields. Need to pull up a list of employees in a specific department or update their contact info? A simple API call is all it takes.
- Time-Off Tracking Done Right: Keep track of employee vacations, sick days, and other leaves with ease. The API lets you manage leave requests, check balances, and approve or deny requests all through automated workflows.
- Custom Fields: Do you track custom HR data, like certifications or uniform sizes? The API can help retrieve or update these custom fields to make sure every piece of data fits your needs.
- Job Postings & Recruitment: Create, update, and manage job postings directly from BambooHR. Integrate your recruitment workflows and track applicants seamlessly with the API.
- Reporting and Analytics: Extract workforce data to generate detailed, real-time reports. Whether it’s turnover trends or department-specific performance insights, BambooHR makes reporting flexible and powerful.
- Payroll Integration: Sync employee data directly with payroll systems to automate payments, taxes, and benefits, reducing manual errors and saving time.
Authentication Best Practices
Security is key when working with the BambooHR API. The API offers two main authentication methods: OAuth 2.0 and API keys.
- OAuth 2.0: For more secure and scalable access, BambooHR recommends OAuth 2.0. This method requires a client ID and secret to generate tokens. Make sure to refresh your tokens regularly to avoid authentication issues.
- API Keys: If your use case doesn’t require complex security layers, API keys are a simpler alternative. Each request needs to include your key in the header to authenticate.
Whichever method you choose, make sure to handle your credentials securely and follow best practices such as rotating keys and limiting permissions based on need.
Commonly Used API Endpoints
Here are some popular API endpoints you’ll likely be using:
- /employees: Retrieve, update, or create employee records.
- /time_off/requests: Submit or check the status of time-off requests.
- /jobs: Create and manage job openings, track applicants, or update job statuses.
- /custom_reports: Generate reports tailored to your specific HR needs using employee data and other custom parameters.
These are just a few, but BambooHR offers a wide range of endpoints to suit various HR tasks, ensuring your integration is as comprehensive as you need it to be.
Real-World Use Cases
Let’s look at how companies are using the BambooHR API in their day-to-day operations:
- Automating Employee Onboarding: Companies can use the BambooHR API to streamline onboarding by automatically creating new employee profiles and updating relevant fields based on information from offer letters or HR systems.
- Syncing Payroll and Benefits: Businesses integrate the BambooHR API with payroll systems, ensuring employee salaries, bonuses, and deductions are calculated automatically, reducing errors and administrative time.
- Time-Off Approval Workflows: Set up workflows where time-off requests are automatically routed for approval, with reminders sent to managers if no action is taken. Once approved, the leave balance is automatically updated.
- Custom Dashboards for HR Metrics: Companies use the API to pull real-time data into custom dashboards, providing insights into workforce trends like attendance, turnover, and performance at a glance.
Troubleshooting Tips
Here are some common issues you might encounter while working with the BambooHR API and how to solve them:
- Invalid Token: If you’re seeing an "invalid token" error, your OAuth token may have expired. Make sure your token refresh mechanism is working properly and tokens are regenerated before they expire.
- Rate Limiting: BambooHR has API rate limits in place. If you exceed the limits, you’ll receive an error. To avoid this, consider batching your requests or spreading them out over time.
- Data Sync Delays: Sometimes, updates to employee data may not appear immediately in the API response due to background processing. Make sure your application accounts for this slight delay, especially when dealing with time-sensitive data.
API Request Limits
Free Plan
100 requests per minute
Standard Plan
1,000 requests per minute
Professional Plan
5,000 requests per minute
Premier Plan
10,000 requests per minute
SDKs
APIs
Method: GET
Description: Retrieve all Benefits.
Endpoint: api/v1/benefits
Parameters:
Method: POST
Description: Create a Benefit.
Endpoint: api/v1/benefits
Parameters: name, description, benefit_type
Method: PUT
Description: Update a Benefit.
Endpoint: api/v1/benefits/{benefitId}
Parameters: id, name, description, benefit_type
Method: DELETE
Description: Delete a Benefit.
Endpoint: api/v1/benefits/{benefitId}
Parameters: id
Method: GET
Description: Retrieve all Certifications.
Endpoint: api/v1/certifications
Parameters:
Method: POST
Description: Create a Certification.
Endpoint: api/v1/certifications
Parameters: name, description, user_ids
Method: DELETE
Description: Delete a Certification.
Endpoint: api/v1/certifications/{certificationId}
Parameters: id
Method: GET
Description: Retrieve all Departments.
Endpoint: api/v1/departments
Parameters:
Method: POST
Description: Create a Department.
Endpoint: api/v1/departments
Parameters: name, manager_id
Method: PUT
Description: Update a Department.
Endpoint: api/v1/departments/{departmentId}
Parameters: id, name, manager_id
Method: DELETE
Description: Delete a Department.
Endpoint: api/v1/departments/{departmentId}
Parameters: id
Method: GET
Description: Retrieve all Document Categories.
Endpoint: api/v1/documents/categories
Parameters:
Method: POST
Description: Create a Document Category.
Endpoint: api/v1/documents/categories
Parameters: name, description
Method: PUT
Description: Update a Document Category.
Endpoint: api/v1/documents/categories/{documentCategoryId}
Parameters: id, name, description
Method: DELETE
Description: Delete a Document Category.
Endpoint: api/v1/documents/categories/{documentCategoryId}
Parameters: id
Method: GET
Description: Retrieve all Documents.
Endpoint: api/v1/documents
Parameters:
Method: POST
Description: Create a Document.
Endpoint: api/v1/documents
Parameters: name, file_name, document_category_id
Method: PUT
Description: Update a Document.
Endpoint: api/v1/documents/{documentId}
Parameters: id, name, file_name, document_category_id, terminated
Method: DELETE
Description: Delete a Document.
Endpoint: api/v1/documents/{documentId}
Parameters: id
Method: GET
Description: Retrieve all Earning Types.
Endpoint: api/v1/earningtypes
Parameters:
Method: POST
Description: Create an Earning Type.
Endpoint: api/v1/earningtypes
Parameters: name, description, pay_component, display_order, custom, taxable, garnish, pto, gross_up_on_import, deduction, subject_to_social_security, subject_to_medicare, subject_to_fica, subject_to_federal_unemployment, subject_to_state_unemployment, subject_to_seasonal_unemployment, units_per_hour
Method: PUT
Description: Update an Earning Type.
Endpoint: api/v1/earningtypes/{earningTypeId}
Parameters: id, name, description, pay_component, display_order, custom, taxable, garnish, pto, gross_up_on_import, deduction, subject_to_social_security, subject_to_medicare, subject_to_fica, subject_to_federal_unemployment, subject_to_state_unemployment, subject_to_seasonal_unemployment, units_per_hour
Method: DELETE
Description: Delete an Earning Type.
Endpoint: api/v1/earningtypes/{earningTypeId}
Parameters: id
Method: GET
Description: Retrieve all Employees.
Endpoint: api/v1/employees
Parameters:
Method: POST
Description: Create an Employee.
Endpoint: api/v1/employees
Parameters: first_name, middle_name, last_name, maiden_name, suffix, ssn, street1, street2, city, state, country, zip, phone, mobile, email, work_email, ethnicity, gender, marital_status, birth_date, hire_date, termination_date, termination_reason, title, department_id, manager_id, emp_status, pay_group, work_location, annual_salary, commission, hourly_wage, hours_per_week, pay_frequency, direct_deposit_account_number, direct_deposit_routing_number, fica_withholding_allowance, federal_withholding_allowance, state_withholding_allowance, local_withholding_allowance, additional_withholding, exemptions, benefits, certifications, custom_fields, documents, eeoc, i9, rehire_date, job_title, shift, cost_center, pay_rate_type, gross_pay_stub_display_name, net_pay_stub_display_name, year_to_date_pay_stub_display_name, pay_rate, pay_schedule_policy_id, total_comp_display_name, total_comp, pto_accrual_method, e_verify_status, e_verify_case_number, e_verify_employer_agent_authorization_date, e_verify_expiration_date, last_performance_review_date, next_performance_review_date
Method: PUT
Description: Update an Employee.
Endpoint: api/v1/employees/{employeeId}
Parameters: id, first_name, middle_name, last_name, maiden_name, suffix, ssn, street1, street2, city, state, country, zip, phone, mobile, email, work_email, ethnicity, gender, marital_status, birth_date, hire_date, termination_date, termination_reason, title, department_id, manager_id, emp_status, pay_group, work_location, annual_salary, commission, hourly_wage, hours_per_week, pay_frequency, direct_deposit_account_number, direct_deposit_routing_number, fica_withholding_allowance, federal_withholding_allowance, state_withholding_allowance, local_withholding_allowance, additional_withholding, exemptions, benefits, certifications, custom_fields, documents, eeoc, i9, rehire_date, job_title, shift, cost_center, pay_rate_type, gross_pay_stub_display_name, net_pay_stub_display_name, year_to_date_pay_stub_display_name, pay_rate, pay_schedule_policy_id, total_comp_display_name, total_comp, pto_accrual_method, e_verify_status, e_verify_case_number, e_verify_employer_agent_authorization_date, e_verify_expiration_date, last_performance_review_date, next_performance_review_date
Method: DELETE
Description: Delete an Employee.
Endpoint: api/v1/employees/{employeeId}
Parameters: id
Method: GET
Description: Retrieve all Goals.
Endpoint: api/v1/goals
Parameters:
Method: POST
Description: Create a Goal.
Endpoint: api/v1/goals
Parameters: title, description, percentage_complete, visible_to_employees, assign_to_all_employees, default_due_date, default_reminder_period, manager_visible_only
Method: PUT
Description: Update a Goal.
Endpoint: api/v1/goals/{goalId}
Parameters: id, title, description, percentage_complete, visible_to_employees, assign_to_all_employees, default_due_date, default_reminder_period, manager_visible_only
Method: DELETE
Description: Delete a Goal.
Endpoint: api/v1/goals/{goalId}
Parameters: id
Method: GET
Description: Retrieve all Job Applications.
Endpoint: api/v1/jobapplications
Parameters:
Method: POST
Description: Create a Job Application.
Endpoint: api/v1/jobapplications
Parameters: opening_id, first_name, middle_name, last_name, email, phone, resume, cover_letter, custom_questions
Method: PUT
Description: Update a Job Application.
Endpoint: api/v1/jobapplications/{jobApplicationId}
Parameters: id, opening_id, first_name, middle_name, last_name, email, phone, resume, cover_letter, custom_questions
Method: DELETE
Description: Delete a Job Application.
Endpoint: api/v1/jobapplications/{jobApplicationId}
Parameters: id
Method: GET
Description: Retrieve all Job Openings.
Endpoint: api/v1/jobopenings
Parameters:
Method: POST
Description: Create a Job Opening.
Endpoint: api/v1/jobopenings
Parameters: title, description, department_id, employment_type, location
Method: PUT
Description: Update a Job Opening.
Endpoint: api/v1/jobopenings/{jobOpeningId}
Parameters: id, title, description, department_id, employment_type, location
Method: DELETE
Description: Delete a Job Opening.
Endpoint: api/v1/jobopenings/{jobOpeningId}
Parameters: id
Method: GET
Description: Retrieve all Notes.
Endpoint: api/v1/notes
Parameters:
Method: POST
Description: Create a Note.
Endpoint: api/v1/notes
Parameters: employee_id, note_type, subject, note, author
Method: PUT
Description: Update a Note.
Endpoint: api/v1/notes/{noteId}
Parameters: id, employee_id, note_type, subject, note, author
Method: DELETE
Description: Delete a Note.
Endpoint: api/v1/notes/{noteId}
Parameters: id
Method: GET
Description: Retrieve all Pay Groups.
Endpoint: api/v1/paygroups
Parameters:
Method: POST
Description: Create a Pay Group.
Endpoint: api/v1/paygroups
Parameters: name, termination_types, pay_periods, pto_accrual_method, calculate_overtime, allow_negative_balances, deduction_ordering, earning_order, additional_pay_components
Method: PUT
Description: Update a Pay Group.
Endpoint: api/v1/paygroups/{payGroupId}
Parameters: id, name, termination_types, pay_periods, pto_accrual_method, calculate_overtime, allow_
FAQ
How do I authenticate to the BambooHR API?
You can authenticate to the BambooHR API using OAuth 2.0 with the Authorization Code Grant flow.
What are the rate limits for the BambooHR API?
The rate limits for the BambooHR API are based on a tiered system. The default tier has a limit of 10 requests per second.
How do I get a sandbox account for testing the BambooHR API?
You can request a sandbox account by filling out the form at https://www.bamboohr.com/sandbox-sign-up.
How do I create a developer account for the BambooHR API?
You can create a developer account by visiting https://developer.bamboohr.com.
What is the difference between a 'field' and a 'label' in the BambooHR API?
In the BambooHR API, a 'field' is the programmatic name for a piece of data, while a 'label' is the human-readable name for the same data.