BambooHR
Use this page to set up the BambooHR source connector and find reference information.
What you need
- A BambooHR account with access to the data you want to sync.
- A BambooHR API key. API requests use the permissions of the user who generated the key. Choose a user who can view the employees, time off and time tracking data you want to sync.
- Your BambooHR company subdomain. If you access BambooHR at
https://mycompany.bamboohr.com, your subdomain ismycompany.
Generate an API key
- Log in to BambooHR.
- Select your name in the lower-left corner of any page to open the user menu.
- Select API Keys. This option only appears if you have sufficient permissions.
- Create a new API key. Copy it and store it securely.
For more information, see the BambooHR API documentation.
Set up the connector
- In Airbyte, go to Sources and select New source.
- Select BambooHR from the list of sources.
- Enter a name for the source.
- For api_key, enter your BambooHR API key.
- For subdomain, enter your BambooHR company subdomain.
- Optional: For custom_reports_fields, enter a comma-separated list of BambooHR field names to request in the
custom_reports_streamstream. For example, enterfirstName,lastName,department. The connector only requests the fields you list. Enter every field you want in that stream. - Optional: For employee_fields, enter a comma-separated list of BambooHR field names to request in the
employeesstream. The default isfirstName,lastName. - Optional: For Start date, enter the UTC date and time for starting the
time_off_requests_streamandtimesheet_entriesstream syncs. Use the formatYYYY-MM-DDTHH:MM:SSZ. If left blank, the connector syncs data from about 31 days before the current date. - Select Set up source.
The configuration form includes custom_reports_include_default_fields, but the current connector version doesn’t use it. To include fields in the custom_reports_stream stream, list them in custom_reports_fields.
Supported sync modes
The BambooHR source connector supports these sync modes:
| Feature | Supported? |
|---|---|
| Full Refresh Sync | Yes |
| Incremental - Append Sync | Yes |
| Namespaces | No |
Supported streams
| Stream | BambooHR endpoint | Primary key | Incremental | Notes |
|---|---|---|---|---|
custom_reports_stream | Request a custom report | None | No | One record per employee, containing the fields listed in custom_reports_fields. |
employees_directory_stream | Get employee directory | id | No | Returns only employees and fields that your company shares in its Company Directory settings. |
employees | Get employee | None | Yes | Requests each employee from employees_directory_stream with the fields listed in employee_fields. Every sync reads all employees. |
meta_fields_stream | Get a list of fields | None | No | Lists the fields available in your BambooHR account. Use it to find field names for custom_reports_fields and employee_fields. |
time_off_requests_stream | Get time off requests | None | Yes | Cursor field: created. Each incremental sync re-reads the previous 365 days to capture updated requests. |
timesheet_entries | Get timesheet entries | id | Yes | Cursor field: start. |
Limitations and troubleshooting
Expand to see details about BambooHR connector limitations and troubleshooting.
Rate limits
BambooHR doesn’t publish fixed rate limits, but may throttle requests it considers too frequent. BambooHR then returns an HTTP 429 response with a Retry-After header. The connector retries the request. For more information, see the BambooHR technical overview.
Permission errors
An HTTP 403 error means the API key’s user can’t access that stream’s data. Use an API key from a user with the required access. The employees_directory_stream stream and its dependent employees stream also return 403 in one case. This happens when the Company Directory isn’t shared with the API key user’s access level.
Check the connection
The connector checks the connection by reading meta_fields_stream. If it returns an HTTP 404 error, verify your subdomain.
IP allow list
If you use Airbyte Cloud and restrict access to specific IPs, add the Airbyte Cloud IP addresses to your allow list.
Changelog
Expand to review
| Version | Date | Pull Request | Subject |
|---|---|---|---|
| 0.10.0 | 2026-11-10 | 91540 | Expand declared fields and improve timesheet and time-off incremental sync reliability. |
| 0.9.4 | 2026-11-10 | 91320 | Upgrade base image to source-declarative-manifest 7.47.0 |
| 0.9.3 | 2025-05-24 | 60660 | Update dependencies |
| 0.9.2 | 2025-05-10 | 59340 | Update dependencies |
| 0.9.1 | 2025-04-26 | 58243 | Update dependencies |
| 0.9.0 | 2025-04-14 | 57587 | change how to collect custom fields for custom reports |
| 0.8.3 | 2025-04-12 | 57604 | Update dependencies |
| 0.8.2 | 2025-04-05 | 57190 | Update dependencies |
| 0.8.1 | 2025-03-29 | 56627 | Update dependencies |
| 0.8.0 | 2025-03-25 | 54688 | Add employees stream |
| 0.7.3 | 2025-03-22 | 56137 | Update dependencies |
| 0.7.2 | 2025-03-08 | 55362 | Update dependencies |
| 0.7.1 | 2025-03-01 | 54842 | Update dependencies |
| 0.7.0 | 2025-02-27 | 54701 | Add timesheet_entrees stream |
| 0.6.2 | 2025-02-22 | 54238 | Update dependencies |
| 0.6.1 | 2025-02-15 | 53873 | Update dependencies |
| 0.6.0 | 2024-12-02 | 48759 | Fix incremental for TimeOff Requests stream |
| 0.5.9 | 2025-02-08 | 53441 | Update dependencies |
| 0.5.8 | 2025-02-01 | 52909 | Update dependencies |
| 0.5.7 | 2025-01-25 | 52201 | Update dependencies |
| 0.5.6 | 2025-01-18 | 51771 | Update dependencies |
| 0.5.5 | 2025-01-11 | 51263 | Update dependencies |
| 0.5.4 | 2024-12-28 | 50440 | Update dependencies |
| 0.5.3 | 2024-12-21 | 50206 | Update dependencies |
| 0.5.2 | 2024-12-14 | 49543 | Update dependencies |
| 0.5.1 | 2024-12-12 | 49025 | Update dependencies |
| 0.5.0 | 2024-10-28 | 47262 | Migrate to Manifest-only |
| 0.4.14 | 2024-10-28 | 47072 | Update dependencies |
| 0.4.13 | 2024-10-12 | 46842 | Update dependencies |
| 0.4.12 | 2024-10-05 | 46500 | Update dependencies |
| 0.4.11 | 2024-09-28 | 46157 | Update dependencies |
| 0.4.10 | 2024-09-21 | 45766 | Update dependencies |
| 0.4.9 | 2024-09-14 | 45542 | Update dependencies |
| 0.4.8 | 2024-09-07 | 45210 | Update dependencies |
| 0.4.7 | 2024-08-31 | 44978 | Update dependencies |
| 0.4.6 | 2024-08-24 | 44652 | Update dependencies |
| 0.4.5 | 2024-08-17 | 44272 | Update dependencies |
| 0.4.4 | 2024-08-12 | 43851 | Update dependencies |
| 0.4.3 | 2024-08-10 | 43467 | Update dependencies |
| 0.4.2 | 2024-08-03 | 43154 | Update dependencies |
| 0.4.1 | 2024-07-27 | 42779 | Update dependencies |
| 0.4.0 | 2024-07-18 | 41443 | Add TimeOff Requests stream |
| 0.3.8 | 2024-07-20 | 42200 | Update dependencies |
| 0.3.7 | 2024-07-13 | 41780 | Update dependencies |
| 0.3.6 | 2024-07-10 | 41437 | Update dependencies |
| 0.3.5 | 2024-07-09 | 41088 | Update dependencies |
| 0.3.4 | 2024-07-06 | 40818 | Update dependencies |
| 0.3.3 | 2024-06-25 | 40288 | Update dependencies |
| 0.3.2 | 2024-06-22 | 40156 | Update dependencies |
| 0.3.1 | 2024-06-06 | 39201 | [autopull] Upgrade base image to v1.2.2 |
| 0.3.0 | 2024-05-25 | 37452 | Migrate to Low Code |
| 0.2.6 | 2024-04-19 | 37124 | Updating to 0.80.0 CDK |
| 0.2.5 | 2024-04-18 | 37124 | Manage dependencies with Poetry. |
| 0.2.4 | 2024-04-15 | 37124 | Base image migration: remove Dockerfile and use the python-connector-base image |
| 0.2.3 | 2024-04-12 | 37124 | schema descriptions |
| 0.2.2 | 2022-09-16 | 17684 | Fix custom field validation retrieve |
| 0.2.1 | 2022-09-16 | 16826 | Add custom fields validation during check |
| 0.2.0 | 2022-03-24 | 11326 | Add support for Custom Reports endpoint |
| 0.1.0 | 2021-08-27 | 5054 | Initial release with Employees API |