> For the complete documentation index, see [llms.txt](https://docs.planetcrust.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.planetcrust.com/human-connections/bamboohr/bamboohr.md).
# BambooHR
Try @Human Buy @Human Subscription Join @Human Community
Put BambooHR to Work with @Human Automations and @Human Agents
The BambooHR Connection documents all Triggers, Actions and Query Operations available for creating automations via the BambooHR API.
{% embed url="" %}
#### What can you do with the BambooHR Connection?
* Connect to the BambooHR API in a few clicks
* Use the related BambooHR Operations (see below) in @Human Automations or @Human Agents
### Related Operations
#### Trigger Operations
**Employee Created**
Triggers on: employees/employee\_created
Triggered when a new employee record is created in BambooHR.
**Employee Updated**
Triggers on: employees/employee\_updated
Triggered when an existing employee's information is updated in BambooHR.
**Time Off Request Created**
Triggers on: time\_off\_requests/time\_off\_request\_created
Triggered when a new time off request is submitted in BambooHR.
**Time Off Request Updated**
Triggers on: time\_off\_requests/time\_off\_request\_updated
Triggered when the status or details of a time off request are updated in BambooHR.
#### Action Operations
[Action: Add Timesheet Clock Entries](/human-connections/bamboohr/bamboohr/action-create-a-project.md)
[Action: Update Employee](/human-connections/bamboohr/bamboohr/action-update-employee.md)
[Action: API Request](/human-connections/bamboohr/bamboohr/action-api-request.md)
#### Query Operations
[Query: Get Summary of Who's Out](/human-connections/bamboohr/bamboohr/query-get-summary-of-whos-out.md)
### Related Automations
Example link
### Obtaining Access Credentials
To obtain a **Personal Access Token (PAT)** for **BambooHR**, follow these steps:
#### **Prerequisites**
* **Admin access** to the BambooHR account (or a user with permission to generate API tokens).
#### **Steps**
1. **Log in** to your BambooHR account.
2. **Navigate** to:
* Click your **profile icon** (top-right) → **"Settings"** → **"API Keys"** (under "Company Settings").
3. **Generate a new token**:
* Click **"Add New API Key"**.
* Enter a **name** for the token (e.g., "System Integration").
* Set **permissions** (select the required scopes for your use case).
4. **Save & copy the token**:
* Click **"Save"**.
* **Copy the generated token** (it will only be shown once).
#### **Required Values**
* **BambooHR Subdomain** (e.g., `yourcompany.bamboohr.com`).
* **API Key (PAT)** (generated above).
### Configuring Webhooks
1. **Log in** to your BambooHR account.
2. **Navigate** to **Settings** (gear icon) → **Account** → **Webhooks**.
3. Click the **+ Add Webhook** button.
4. Enter a **name** for the webhook.
5. Select the **Monitored Fields** that should trigger the webhook.
6. Select the **Posted Fields** to be included in the data payload.
7. Choose the **Data Format** (JSON is recommended).
8. Enter the **Post to URL**.
9. Click **+ Generate Key** to create a **Private Signature Key**.
10. **Copy the signature key** immediately (it won’t be shown again).
11. Click **Save**.
### Code (Apache v2.0): Service Connectivity and Metadata
```
{
"handle": "bamboohr",
"status": "active",
"meta": {
"short": "BambooHR",
"description": "A connector for integrating with BambooHR's API to manage employee data, time tracking, and HR workflows.",
"icon": "bamboohr",
"tags": ["HR", "Employee Management", "API"]
},
"service": {
"baseURL": {
"value": "https://api.bamboohr.com/api/gateway.php/{{companyDomain}}"
},
"protocol": "https",
"contentType": "application/json",
"headers": {
"Accept": {
"value": "application/json"
}
},
"auth": {
"method": "basic",
"params": {
"basic": {
"username": {
"value": "{{apiKey}}",
"placeholders": [
{
"name": "apiKey",
"type": "String",
"description": "BambooHR API key",
"required": true
}
]
},
"password": {
"value": "x",
"placeholders": []
}
}
}
}
}
}
```
### Code (Apache v2.0): List of External Resources and Internal Mapping
```
[
{
"handle": "employees",
"meta": {
"short": "Employees",
"description": "Manage employee records including personal details, job information, and employment status."
},
"endpoint": {
"value": "/employees/directory",
"placeholders": []
},
"fields": [
{
"name": "id",
"type": "Integer",
"selector": [
"id"
],
"meta": {
"description": "Unique identifier for the employee."
}
},
{
"name": "firstName",
"type": "String",
"selector": [
"firstName"
],
"meta": {
"description": "First name of the employee."
}
},
{
"name": "lastName",
"type": "String",
"selector": [
"lastName"
],
"meta": {
"description": "Last name of the employee."
}
},
{
"name": "jobTitle",
"type": "String",
"selector": [
"jobTitle"
],
"meta": {
"description": "Current job title of the employee."
}
},
{
"name": "workEmail",
"type": "String",
"selector": [
"workEmail"
],
"meta": {
"description": "Work email address of the employee."
}
},
{
"name": "workPhone",
"type": "String",
"selector": [
"workPhone"
],
"meta": {
"description": "Work phone number of the employee."
}
},
{
"name": "hireDate",
"type": "String",
"selector": [
"hireDate"
],
"meta": {
"description": "Date when the employee was hired."
}
},
{
"name": "employmentStatus",
"type": "String",
"selector": [
"employmentStatus"
],
"meta": {
"description": "Current employment status of the employee."
}
}
],
"operations": {
"list": {
"method": "GET",
"path": {
"value": "",
"placeholders": []
},
"headers": {},
"queryParams": {},
"bodyTemplate": null
},
"read": {
"method": "GET",
"path": {
"value": "/{{id}}",
"placeholders": [
{
"name": "id",
"type": "Integer",
"description": "The employee ID.",
"required": true
}
]
},
"headers": {},
"queryParams": {},
"bodyTemplate": null
}
},
"webhooks": [
{
"event": "employee_created",
"path": "/webhooks/bamboohr/employee_created",
"payload": [
{
"name": "employeeId",
"type": "Integer",
"selector": [
"employeeId"
],
"meta": {
"description": "ID of the created employee."
}
},
{
"name": "eventType",
"type": "String",
"selector": [
"eventType"
],
"meta": {
"description": "Type of webhook event."
}
}
]
},
{
"event": "employee_updated",
"path": "/webhooks/bamboohr/employee_updated",
"payload": [
{
"name": "employeeId",
"type": "Integer",
"selector": [
"employeeId"
],
"meta": {
"description": "ID of the updated employee."
}
},
{
"name": "eventType",
"type": "String",
"selector": [
"eventType"
],
"meta": {
"description": "Type of webhook event."
}
}
]
}
]
},
{
"handle": "time_off_requests",
"meta": {
"short": "Time Off Requests",
"description": "Manage time off requests including approvals and balances."
},
"endpoint": {
"value": "/time_off/requests",
"placeholders": []
},
"fields": [
{
"name": "id",
"type": "Integer",
"selector": [
"id"
],
"meta": {
"description": "Unique identifier for the time off request."
}
},
{
"name": "employeeId",
"type": "Integer",
"selector": [
"employeeId"
],
"meta": {
"description": "ID of the employee who made the request."
}
},
{
"name": "startDate",
"type": "String",
"selector": [
"start"
],
"meta": {
"description": "Start date of the time off request."
}
},
{
"name": "endDate",
"type": "String",
"selector": [
"end"
],
"meta": {
"description": "End date of the time off request."
}
},
{
"name": "status",
"type": "String",
"selector": [
"status"
],
"meta": {
"description": "Current status of the time off request."
}
},
{
"name": "type",
"type": "String",
"selector": [
"type"
],
"meta": {
"description": "Type of time off requested."
}
}
],
"operations": {
"list": {
"method": "GET",
"path": {
"value": "",
"placeholders": []
},
"headers": {},
"queryParams": {
"start": {
"value": "{{startDate}}",
"placeholders": [
{
"name": "startDate",
"type": "String",
"description": "Start date for filtering requests.",
"required": false
}
]
},
"end": {
"value": "{{endDate}}",
"placeholders": [
{
"name": "endDate",
"type": "String",
"description": "End date for filtering requests.",
"required": false
}
]
}
},
"bodyTemplate": null
},
"create": {
"method": "POST",
"path": {
"value": "",
"placeholders": []
},
"headers": {
"Content-Type": {
"value": "application/json",
"placeholders": []
}
},
"queryParams": {},
"bodyTemplate": {
"value": "{\"employeeId\": {{employeeId}}, \"start\": \"{{startDate}}\", \"end\": \"{{endDate}}\", \"type\": \"{{type}}\"}",
"placeholders": [
{
"name": "employeeId",
"type": "Integer",
"description": "ID of the employee.",
"required": true
},
{
"name": "startDate",
"type": "String",
"description": "Start date of the time off.",
"required": true
},
{
"name": "endDate",
"type": "String",
"description": "End date of the time off.",
"required": true
},
{
"name": "type",
"type": "String",
"description": "Type of time off.",
"required": true
}
]
}
}
},
"webhooks": [
{
"event": "time_off_request_created",
"path": "/webhooks/bamboohr/time_off_request_created",
"payload": [
{
"name": "requestId",
"type": "Integer",
"selector": [
"requestId"
],
"meta": {
"description": "ID of the created time off request."
}
},
{
"name": "employeeId",
"type": "Integer",
"selector": [
"employeeId"
],
"meta": {
"description": "ID of the employee who made the request."
}
}
]
},
{
"event": "time_off_request_updated",
"path": "/webhooks/bamboohr/time_off_request_updated",
"payload": [
{
"name": "requestId",
"type": "Integer",
"selector": [
"requestId"
],
"meta": {
"description": "ID of the updated time off request."
}
},
{
"name": "status",
"type": "String",
"selector": [
"status"
],
"meta": {
"description": "Updated status of the time off request."
}
}
]
}
]
},
{
"handle": "employee_files",
"meta": {
"short": "Employee Files",
"description": "Manage files and documents associated with employee records."
},
"endpoint": {
"value": "/employees/{{employeeId}}/files/view",
"placeholders": [
{
"name": "employeeId",
"type": "Integer",
"description": "The ID of the employee.",
"required": true
}
]
},
"fields": [
{
"name": "id",
"type": "Integer",
"selector": [
"id"
],
"meta": {
"description": "Unique identifier for the file."
}
},
{
"name": "name",
"type": "String",
"selector": [
"name"
],
"meta": {
"description": "Name of the file."
}
},
{
"name": "originalFileName",
"type": "String",
"selector": [
"originalFileName"
],
"meta": {
"description": "Original name of the uploaded file."
}
},
{
"name": "size",
"type": "String",
"selector": [
"size"
],
"meta": {
"description": "File size."
}
},
{
"name": "dateCreated",
"type": "String",
"selector": [
"dateCreated"
],
"meta": {
"description": "Date the file was added."
}
},
{
"name": "createdBy",
"type": "String",
"selector": [
"createdBy"
],
"meta": {
"description": "User who uploaded the file."
}
}
],
"operations": {
"list": {
"method": "GET",
"path": {
"value": "",
"placeholders": []
},
"headers": {},
"queryParams": {},
"bodyTemplate": null
},
"read": {
"method": "GET",
"path": {
"value": "/{{fileId}}",
"placeholders": [
{
"name": "fileId",
"type": "Integer",
"description": "The ID of the file.",
"required": true
}
]
},
"headers": {},
"queryParams": {},
"bodyTemplate": null
}
},
"webhooks": []
},
{
"handle": "employee_dependents",
"meta": {
"short": "Employee Dependents",
"description": "Manage the dependents associated with an employee."
},
"endpoint": {
"value": "/employees/{{employeeId}}/dependents",
"placeholders": [
{
"name": "employeeId",
"type": "Integer",
"description": "The ID of the employee.",
"required": true
}
]
},
"fields": [
{
"name": "id",
"type": "Integer",
"selector": [
"id"
],
"meta": {
"description": "Unique identifier for the dependent."
}
},
{
"name": "firstName",
"type": "String",
"selector": [
"firstName"
],
"meta": {
"description": "First name of the dependent."
}
},
{
"name": "lastName",
"type": "String",
"selector": [
"lastName"
],
"meta": {
"description": "Last name of the dependent."
}
},
{
"name": "relationship",
"type": "String",
"selector": [
"relationship"
],
"meta": {
"description": "Relationship of the dependent to the employee."
}
},
{
"name": "gender",
"type": "String",
"selector": [
"gender"
],
"meta": {
"description": "Gender of the dependent."
}
},
{
"name": "dateOfBirth",
"type": "String",
"selector": [
"dateOfBirth"
],
"meta": {
"description": "Date of birth of the dependent."
}
}
],
"operations": {
"list": {
"method": "GET",
"path": {
"value": "",
"placeholders": []
},
"headers": {},
"queryParams": {},
"bodyTemplate": null
}
},
"webhooks": []
},
{
"handle": "employment_status",
"meta": {
"short": "Employment Status",
"description": "Track the employment status changes for employees."
},
"endpoint": {
"value": "/employees/status",
"placeholders": []
},
"fields": [
{
"name": "employeeId",
"type": "Integer",
"selector": [
"employeeId"
],
"meta": {
"description": "ID of the employee."
}
},
{
"name": "status",
"type": "String",
"selector": [
"status"
],
"meta": {
"description": "Current status."
}
},
{
"name": "date",
"type": "String",
"selector": [
"date"
],
"meta": {
"description": "Date of the status change."
}
}
],
"operations": {
"list": {
"method": "GET",
"path": {
"value": "",
"placeholders": []
},
"headers": {},
"queryParams": {},
"bodyTemplate": null
}
},
"webhooks": []
},
{
"handle": "capabilities",
"meta": {
"short": "Goals",
"description": "Manage employee goals and objectives."
},
"endpoint": {
"value": "/performance/goals",
"placeholders": []
},
"fields": [
{
"name": "id",
"type": "Integer",
"selector": [
"id"
],
"meta": {
"description": "Unique identifier of the goal."
}
},
{
"name": "title",
"type": "String",
"selector": [
"title"
],
"meta": {
"description": "Title of the goal."
}
},
{
"name": "status",
"type": "String",
"selector": [
"status"
],
"meta": {
"description": "Status of the goal."
}
},
{
"name": "dueDate",
"type": "String",
"selector": [
"dueDate"
],
"meta": {
"description": "Due date for the goal."
}
},
{
"name": "employeeId",
"type": "Integer",
"selector": [
"employeeId"
],
"meta": {
"description": "ID of the assigned employee."
}
}
],
"operations": {
"list": {
"method": "GET",
"path": {
"value": "",
"placeholders": []
},
"headers": {},
"queryParams": {
"employeeId": {
"value": "{{employeeId}}",
"placeholders": [
{
"name": "employeeId",
"type": "Integer",
"description": "Filter goals by employee ID.",
"required": false
}
]
}
},
"bodyTemplate": null
}
},
"webhooks": []
},
{
"handle": "employee_directory",
"meta": {
"short": "Directory",
"description": "Access the company directory of employees."
},
"endpoint": {
"value": "/employees/directory",
"placeholders": []
},
"fields": [
{
"name": "id",
"type": "Integer",
"selector": [
"id"
],
"meta": {
"description": "Employee ID."
}
},
{
"name": "displayName",
"type": "String",
"selector": [
"displayName"
],
"meta": {
"description": "Full display name."
}
},
{
"name": "jobTitle",
"type": "String",
"selector": [
"jobTitle"
],
"meta": {
"description": "Job title."
}
},
{
"name": "department",
"type": "String",
"selector": [
"department"
],
"meta": {
"description": "Department name."
}
},
{
"name": "location",
"type": "String",
"selector": [
"location"
],
"meta": {
"description": "Work location."
}
}
],
"operations": {
"list": {
"method": "GET",
"path": {
"value": "",
"placeholders": []
},
"headers": {},
"queryParams": {},
"bodyTemplate": null
}
},
"webhooks": []
},
{
"handle": "applicant_tracking",
"meta": {
"short": "Applicants",
"description": "Manage job applicants and recruiting processes."
},
"endpoint": {
"value": "/applicant_tracking/applications",
"placeholders": []
},
"fields": [
{
"name": "id",
"type": "Integer",
"selector": [
"id"
],
"meta": {
"description": "Application ID."
}
},
{
"name": "candidateId",
"type": "Integer",
"selector": [
"candidate",
"id"
],
"meta": {
"description": "Candidate ID."
}
},
{
"name": "jobId",
"type": "Integer",
"selector": [
"job",
"id"
],
"meta": {
"description": "Job ID."
}
},
{
"name": "status",
"type": "String",
"selector": [
"status",
"label"
],
"meta": {
"description": "Application status."
}
},
{
"name": "appliedDate",
"type": "String",
"selector": [
"appliedDate"
],
"meta": {
"description": "Date applied."
}
}
],
"operations": {
"list": {
"method": "GET",
"path": {
"value": "",
"placeholders": []
},
"headers": {},
"queryParams": {},
"bodyTemplate": null
}
},
"webhooks": []
},
{
"handle": "timesheets",
"meta": {
"short": "Timesheets",
"description": "Manage employee time tracking and timesheet entries."
},
"endpoint": {
"value": "/timesheets/entries",
"placeholders": []
},
"fields": [
{
"name": "id",
"type": "Integer",
"selector": [
"id"
],
"meta": {
"description": "Timesheet entry ID."
}
},
{
"name": "employeeId",
"type": "Integer",
"selector": [
"employeeId"
],
"meta": {
"description": "Employee ID."
}
},
{
"name": "date",
"type": "String",
"selector": [
"date"
],
"meta": {
"description": "Date of the entry."
}
},
{
"name": "hours",
"type": "Float",
"selector": [
"hours"
],
"meta": {
"description": "Number of hours worked."
}
},
{
"name": "projectId",
"type": "Integer",
"selector": [
"projectId"
],
"meta": {
"description": "Project ID."
}
}
],
"operations": {
"list": {
"method": "GET",
"path": {
"value": "",
"placeholders": []
},
"headers": {},
"queryParams": {
"start": {
"value": "{{start}}",
"placeholders": [
{
"name": "start",
"type": "String",
"description": "Start date for filtering timesheets.",
"required": false
}
]
},
"end": {
"value": "{{end}}",
"placeholders": [
{
"name": "end",
"type": "String",
"description": "End date for filtering timesheets.",
"required": false
}
]
}
},
"bodyTemplate": null
}
},
"webhooks": []
},
{
"handle": "benefits",
"meta": {
"short": "Benefits",
"description": "Explore and manage employee benefits plans and enrollments."
},
"endpoint": {
"value": "/benefits/plans",
"placeholders": []
},
"fields": [
{
"name": "id",
"type": "Integer",
"selector": [
"id"
],
"meta": {
"description": "Benefit plan ID."
}
},
{
"name": "name",
"type": "String",
"selector": [
"name"
],
"meta": {
"description": "Plan name."
}
},
{
"name": "provider",
"type": "String",
"selector": [
"provider"
],
"meta": {
"description": "Provider name."
}
},
{
"name": "planType",
"type": "String",
"selector": [
"planType"
],
"meta": {
"description": "Type of the benefit plan."
}
}
],
"operations": {
"list": {
"method": "GET",
"path": {
"value": "",
"placeholders": []
},
"headers": {},
"queryParams": {},
"bodyTemplate": null
}
},
"webhooks": []
},
{
"handle": "training",
"meta": {
"short": "Training",
"description": "Track employee training types and completion statuses."
},
"endpoint": {
"value": "/training/type",
"placeholders": []
},
"fields": [
{
"name": "id",
"type": "Integer",
"selector": [
"id"
],
"meta": {
"description": "Training type ID."
}
},
{
"name": "name",
"type": "String",
"selector": [
"name"
],
"meta": {
"description": "Name of the training."
}
},
{
"name": "description",
"type": "String",
"selector": [
"description"
],
"meta": {
"description": "Description of the training."
}
},
{
"name": "required",
"type": "Boolean",
"selector": [
"required"
],
"meta": {
"description": "Indicates if the training is required."
}
}
],
"operations": {
"list": {
"method": "GET",
"path": {
"value": "",
"placeholders": []
},
"headers": {},
"queryParams": {},
"bodyTemplate": null
}
},
"webhooks": []
}
]
```
Try @Human Buy @Human Subscription Join @Human Community
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.planetcrust.com/human-connections/bamboohr/bamboohr.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.