BambooHR

This documentation for the BambooHR integration describes the technical capabilities of this integration, including authorization, scopes/permissions, and utilized endpoints. For more information on how to integrate BambooHR, visit our connection instructions.

Version

This integration utilizes the BambooHR REST API v1.

Base URL

The base URL used for all BambooHR API endpoints contains the Subdomain:

https://api.bamboohr.com/api/gateway.php/subdomain/v1

Endpoints Utilized

DataGrail uses the following endpoints to authorize and test the connection:

Method	Endpoint	Purpose	Docs
GET	/meta/fields	Validate credentials

---

Authentication & Authorization

The DataGrail BambooHR integration connects using API Key authentication which requires an API Key.

Sensitive Credentials

Publicly exposing your API credentials can allow unauthorized access to BambooHR API endpoints by a third party. DataGrail stores your API credentials encrypted and protected.

---

Limits

Limits in BambooHR are calculated using the leaky bucket algorithm. All requests that are made after rate limits have been exceeded are throttled and an HTTP 429 Too Many Requests error is returned. Requests succeed again after enough requests have emptied out of the bucket.

• DataGrail supports requests throttling to stay within 70-80% of specified service rate limits.
• DataGrail processes API responses with HTTP 429 status to interrupt requests, waiting and retrying (using an exponential backoff strategy).

---

Capabilities

Access

DataGrail's BambooHR integration provides Synchronous Access capabilities for the following supported identifier category: Email.

Data Interactions

For Access requests, DataGrail will take the following actions:

1. Identify all fields that are available in an account.
2. Find the employee by email, using one of two methods depending on the bamboohr_report_search configuration option:
   • When enabled, request a custom report that includes every email field in the account.
   • When disabled (default), get the employee directory.
3. Get employee data by specifying a set of fields.
4. Fetch all files from an employee.
5. Fetch all withholding from an employee.
6. Fetch all direct deposits from an employee.
7. Fetch all unpaid stubs from an employee.

DataGrail finds employees using one of two search methods, controlled by the bamboohr_report_search configuration option (Use custom report search checkbox in DataGrail):

Setting	How employees are found	Endpoint
Disabled (default)	Searches the BambooHR Company Directory, matching on work email.	/employees/directory
Enabled	Requests a custom report covering every email field in the account. Works when the Company Directory is disabled.	/reports/custom

Endpoints Utilized

Method	Endpoint	Purpose	Docs
GET	/employee_unpaid_pay_stubs/id	Fetch all unpaid stubs from an employee
GET	/employee_withholding/id	Fetch all withholding from an employee
GET	/employees/id	Get an employee
GET	/employees/id/files/view	List employee files and categories
GET	/employees/directory	Gets employee directory
GET	/meta/fields	Get a list of fields
GET	/mployee_direct_deposit_accounts/id	Fetch all direct deposits from an employee
POST	/reports/custom	Request a custom report

---