BambooHR API
Any instance where an entry in the below configuration has a leading $ represents a parameter that needs to be replaced with a static value.
Parameters in this document:
- $endpoint - The Endpoint represents the data that you would like to ingest into Panoply. Details of the value that should be used here can be found in the API Resources section below.
- $sub_domain - Per BambooHR API documentation, "If you access BambooHR at https://mycompany.bamboohr.com, then the sub_domain is
mycompany". - $base_url - The Base URL will follow the below format:
- https://api.bamboohr.com/api/gateway.php/$sub_domain/$endpoint
- $api_key - The API Key will provide access to the BambooHR API. Per BambooHR API documentation here, to generate an API key, users should log in and click their name in the upper right-hand corner of any page to get to the user context menu. If you have sufficient permissions, there will be an
API Keysoption in that menu to go to the page. - $resource_name - The Resource Name represents the name of the resource to be appended and used as part of the Destination Table name. Details of the value that should be used here can be found in the API Resources section below.
- $data_key - The Data Key represents the location of the data in the API response from the BambooHR API.
- $report_id - This parameter only applies to the Reports API Resource, and represents the id of the report that is being ingested into Panoply. This ID can be found in the URL of the report on the BambooHR platform.
API Resources
| $resource_name | $endpoint | $data_key |
|---|---|---|
| Aggregate Goal Info | v1/performance/employees/{identifier}/goals/aggregate | goals |
| Applications | v1/applicant_tracking/applications | applications |
| Benefit Deduction Types | v1/benefits/settings/deduction_typles_all | |
| Company Locations | v1/applicant_tracking/locations | location |
| Employee Dependents | v1/employeedependents | Employee Dependents |
| Employee Directory | v1/employees/directory | employees |
| Employee Goals | v1/performance/employees/{identifier}/goals | goals |
| Goal Status Counts | v1_1/performance/employees/{identifier}/goals/filters | filters |
| Job Summaries | v1/applicant_tracking/jobs | |
| Reports | v1/reports/$report_id | will vary by report |
| Statuses | v1/applicant_tracking/statuses | |
| Time Off Types | v1/meta/time_off/types | timeOffTypes |
| Time Off Policies | v1/meta/time_off/policies | |
| Time Off Requests | v1/meta/time_off/requests | requests |
For the Aggregate Goal Info, Employee Files and Categories, Employee Goals, Employee Trainings, and Goal Status Counts resources listed above, you will need to include the Fetch List configuration (see below).
Connector configuration
- Base url: $base_url
- Method: GET
- Headers: {"Accept": "application/json"}
- Destination: bamboohr_$resource_name
Destination Table naming convention is ultimately up to you as the data owner. A common structure used for this API is to utilize the resource name within the table name. It is suggested to switch spaces with _ in the destination configuraiton. For example, if collecting the Applications resource, using a name like bamboohr_applications.
Authorization
- Authorization: Basic Auth
- Username: $api_key
Per BambooHR documentation, "Use the secret key as the username and any random string for the password." Per this statement, you can put any string as the password as part of this configuration. Within the BambooHR documentation, they use a value of x, though any string will work.
Fetch list
Only applicable for the Aggregate Goal Info, Employee Files and Categories, Employee Goals, Employee Trainings, and Goal Status Counts resources
- Enable:
- Fetch List From: API
- Fetch url: https://api.bamboohr.com/api/gateway.php/$sub_domain/v1/employees/directory
- Method: GET
- Headers: {"Accept": "application/json"}
- Data key: employees
- Data identifier key: id
- Use identifiers: As single value
Advanced Settings
- Data key: $data_key
For the Reports resource, a Primary Key may need to be defined, depending on the data within the given report. For example, if the unique identifier for a given Report is a combination of "Date" and "EmployeeID", the Primary Key will need to be set to {date}-{employeeid}.