New Integration: BambooHR

Description

Add BambooHR integration to sync HR data including employee records, time-off, onboarding, performance, and organizational data into CORE.

Reference Implementations

Existing Integrations (use as templates)

• integrations/hubspot/ - Similar business data system
• integrations/linear/ - Project management integration
• integrations/slack/ - For reference

Required Files Structure

integrations/bamboohr/
├── src/
│   ├── index.ts          # Main entry, OAuth spec
│   ├── schedule.ts       # Sync logic
│   ├── utils.ts          # BambooHR API utilities
│   ├── account-create.ts # OAuth setup
│   └── create-activity.ts # Activity formatting
├── package.json
├── tsup.config.ts
└── README.md

BambooHR API Integration

OAuth Setup

• Use OAuth 2.0 authorization (recommended for all new integrations)
• Legacy API key authentication also supported but not recommended
• OpenID Connect Login API available for SSO
• Base URL: https://{companyDomain}.bamboohr.com/api/gateway.php/{companyDomain}/v1/
• Developer docs: https://documentation.bamboohr.com/

Key Endpoints

• GET /employees/directory - Employee directory
• GET /employees/{id} - Get employee details
• POST /employees - Add new employee
• GET /time_off/requests - Time-off requests
• GET /reports/{id} - Generate reports
• GET /applicant_tracking/applications - Applicant tracking
• GET /performance/review - Performance reviews
• GET /tables/{table} - Custom tables
• Webhook endpoints for real-time events

Events to Track

1. Employee Management - New hire, termination, profile update, department change
2. Time Off - Request submitted, approved, denied, cancelled
3. Onboarding - Task completed, document signed, training finished
4. Performance - Review submitted, goal updated, feedback received
5. Applicant Tracking - Application received, interview scheduled, offer sent

Implementation Tasks

• Set up basic integration structure following integrations/github/src/index.ts pattern
• Implement OAuth 2.0 flow in account-create.ts
• Create API utilities in utils.ts for BambooHR API calls
• Implement sync logic in schedule.ts for employee and HR data
• Convert HR events to CORE activity format
• Add error handling and rate limiting
• Create integration documentation
• Add to integrations/README.md

Technical Notes

• RESTful API built around semantically meaningful HTTPS requests
• Can manipulate employee data and generate reports in several formats
• Official SDKs available with authentication, error handling, retries, and typed models
• Company domain is tenant-specific and part of the API base URL
• Webhooks available for real-time event notifications

Resources

• BambooHR API - Getting Started
• BambooHR API - Technical Overview
• BambooHR Official SDKs
• BambooHR OpenID Connect
• BambooHR API Support

Labels

enhancement, integration, new-feature

Start by reading integrations/github/src/index.ts and the integrations/hubspot/, integrations/linear/, and integrations/slack/ templates. Review the BambooHR API documentation and map the requested OAuth, employee and HR-data sync, activity formatting, and rate-limiting work to the files under integrations/bamboohr/. Done means the requested files exist, the integration is documented, and integrations/README.md includes it.