What is BambooHR?

BambooHR is a cloud-based HR software designed for small to medium businesses. It handles employee records, time-off tracking, performance management, and reporting. Over 30,000 companies use it because it doesn't require an HR degree to operate. If you're building HR integrations, you'll need API access to sync employee data with your other systems.

What You Can Build with BambooHR APIs

The BambooHR API enables programmatic access to:

• Employee Data Management: Read and update employee profiles, compensation, job information
• Time-Off Tracking: Pull PTO balances, submit time-off requests, approve/deny requests programmatically
• Organizational Charts: Extract reporting structures and team hierarchies
• Custom Reports: Build dashboards combining HR data with business metrics
• Onboarding Automation: Trigger workflows when new employees are added

Getting Your BambooHR API Keys: Step-by-Step

Prerequisites

Before starting, ensure you have:

• Admin or Full Access user permissions in BambooHR
• Your company subdomain (format: company.bamboohr.com)
• Clear use case for API access (BambooHR monitors usage)

Step 1: Generate Your API Key

1. Log into your BambooHR account at https://[company].bamboohr.com
2. Click your profile photo in the upper right
3. Select API Keys from the dropdown
4. Click Add New Key
5. Enter a descriptive name (e.g., "Payroll Integration" or "Data Warehouse Sync")
6. Click Generate Key
7. Copy immediately - you won't see this key again

Critical: BambooHR shows the key only once. If you lose it, you'll need to generate a new one.

Step 2: Understand Permission Scope

Unlike other platforms, BambooHR API keys inherit the permissions of the user who created them:

• What you can access via UI = What your API key can access
• Employee visibility: Only employees you can see in BambooHR
• Field access: Only fields visible to your permission level
• Action permissions: Can only perform actions your user role allows

This means if you need full employee access, the API key must be created by an admin user.

Step 3: Test Your Connection

BambooHR uses HTTP Basic Authentication. Test with:

curl https://api.bamboohr.com/api/gateway.php/[company]/v1/employees/directory \ -u "YOUR_API_KEY:x"

Note the :x after your API key - BambooHR requires this format (API key as username, 'x' as password).

Step 4: Handle Subdomain Requirements

Every BambooHR API call requires the company subdomain in the URL:

• Find it in your BambooHR URL: https://[company].bamboohr.com
• Use in API calls: https://api.bamboohr.com/api/gateway.php/[company]/v1/...

Store both the API key and subdomain in your configuration:

BAMBOOHR_API_KEY=your_api_key_here
BAMBOOHR_SUBDOMAIN=yourcompany

Common Integration Patterns

Fetching Employee Data

Get all employees with specific fields:

curl https://api.bamboohr.com/api/gateway.php/[company]/v1/employees/directory \
   -u "YOUR_API_KEY:x" \
   -H "Accept: application/json"

Custom Reports API

For complex data needs, use the custom reports endpoint:

curl -X POST https://api.bamboohr.com/api/gateway.php/[company]/v1/reports/custom \
   -u "YOUR_API_KEY:x" \
   -H "Content-Type: application/json" \
   -d '{
     "fields": ["firstName", "lastName", "department", "hireDate"],
     "filters": {"department": "Engineering"}   }'

Time-Off Balance Tracking

Get PTO balances for an employee:

curl https://api.bamboohr.com/api/gateway.php/[company]/v1/employees/[id]/time_off/calculator \
   -u "YOUR_API_KEY:x" \
   -H "Accept: application/json"

Rate Limits and Best Practices

BambooHR enforces strict rate limits:

• Default: 60 requests per minute
• Burst limit: 120 requests in 2 minutes
• Daily limit: Varies by plan (typically 10,000-50,000)

Headers to monitor:

• X-Rate-Limit-Limit: Your rate limit
• X-Rate-Limit-Remaining: Requests left
• X-Rate-Limit-Reset: When limit resets

Optimization Tips

1. Use field filters: Don't request all fields if you only need a few
2. Implement caching: Employee data doesn't change every minute
3. Batch operations: Use custom reports for bulk data instead of individual employee calls
4. Respect 429 responses: Implement exponential backoff when rate limited

Common Pitfalls

• API Key Visibility: Users can only see/delete their own API keys, not keys created by others
• Permission Changes: If user permissions change, their API key permissions change too
• Terminated Employees: API returns terminated employees by default - filter them in your code
• Date Formats: Inconsistent between endpoints (ISO 8601 vs. MM/DD/YYYY)
• Custom Fields: Must request by field ID, not field name

Alternative: OpenID Connect Authentication

For organizations requiring SSO or building user-facing applications, BambooHR supports OpenID Connect (OIDC) authentication. This is separate from API key authentication and serves different use cases.

When to Use OpenID Connect

Use OIDC when you need:

• Single Sign-On (SSO): Let users log into your app using their BambooHR credentials
• User-specific access: Access BambooHR data based on logged-in user permissions
• Compliance requirements: Meet security standards requiring federated authentication
• No password storage: Avoid storing BambooHR passwords in your application

Setting Up OpenID Connect

Step 1: Register Your Application

1. Log into BambooHR as an admin
2. Navigate to Apps → OpenID Connect
3. Click Register New Application
4. Configure your application:
   • Application Name: Your app's display name
   • Redirect URIs: Your OAuth callback URLs (e.g., https://yourapp.com/auth/callback)
   • Logout URI: Where to redirect after logout
   • Grant Types: Select authorization_code for web apps
5. Save to generate credentials

Step 2: Obtain Credentials After registration, you'll receive:

• Client ID: Your application's unique identifier
• Client Secret: Secret key for token exchange
• Discovery URL: https://[company].bamboohr.com/.well-known/openid-configuration

Step 3: Implement OIDC Flow

1. Authorization Request: Redirect users to:

https://[company].bamboohr.com/oidc/authorize?
     client_id=YOUR_CLIENT_ID&
     response_type=code&
     scope=openid email profile&
     redirect_uri=YOUR_REDIRECT_URI&
     state=RANDOM_STATE

2. Token Exchange: When the user returns with an authorization code:

curl -X POST https://[company].bamboohr.com/oidc/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTHORIZATION_CODE" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "redirect_uri=YOUR_REDIRECT_URI"

3. Access User Info: With the access token:

curl https://[company].bamboohr.com/oidc/userinfo \
  -H "Authorization: Bearer ACCESS_TOKEN"

OIDC vs API Keys: Which to Choose?

Use API Keys when:

• Building backend integrations
• Syncing data between systems
• Running automated reports
• No user interaction required
• Need consistent, service-level access

⠀Use OpenID Connect when:

• Building user-facing applications
• Implementing SSO
• Need user-specific permissions
• Compliance requires federated auth
• Users shouldn't share passwords

⠀Important OIDC Considerations

• Scope limitations: OIDC provides authentication, not full API access
• User context: Access is limited to what the logged-in user can see
• Token expiration: Access tokens expire after 1 hour, refresh tokens after 14 days
• API access: For full API operations, you still need API keys
• Hybrid approach: Many apps use OIDC for auth and API keys for background jobs

Managing BambooHR API Connectivity with Apideck's Vault

If you're integrating BambooHR alongside other HRIS systems, managing different authentication methods and data models becomes complex. Apideck's Vault streamlines this:

• Secure credential storage with monitoring - Store API keys and subdomains securely, with automatic connection health checks
• Pre-built authentication UI - Embedded components handle credential input and validation without custom forms
• Centralized connection management - Monitor all HRIS connections, track API usage, and manage credentials from one dashboard

Here's how to connect BambooHR through Apideck:

1. Navigate to your Apideck dashboard and select Connections
2. Choose BambooHR from the HRIS connectors
3. Enter the credentials:
   • API Key (from Step 1)
   • Company Subdomain
4. Save and click "Test Connection.”
5. Vault validates the credentials and monitors connection health

⠀Once connected, you can access BambooHR data through Apideck's unified HRIS API, meaning the same code works for BambooHR, Workday, ADP, and 40+ other HRIS systems.

Advanced Features

Webhooks

BambooHR supports webhooks for real-time updates:

1. Contact BambooHR support to enable webhooks (not self-service)
2. Provide endpoint URL and events you want
3. Implement signature verification for security
4. Handle employee.add, employee.update, and timeoff.update events

Metadata API

Discover available fields dynamically:

curl https://api.bamboohr.com/api/gateway.php/[company]/v1/meta/fields \
-u "YOUR_API_KEY:x"

This returns all fields, including custom fields, with their IDs and types.

Photo Upload

Upload employee photos (requires specific permissions):

curl -X PUT https://api.bamboohr.com/api/gateway.php/[company]/v1/employees/[id]/photo \ -u "YOUR_API_KEY:x" \
-H "Content-Type: image/jpeg" \
--data-binary @photo.jpg

Testing Strategy

Before production deployment:

1. Use a Sandbox: Request a sandbox account from BambooHR support
2. Test Permission Levels: Create API keys with different user permissions
3. Monitor Rate Limits: Log all 429 responses and adjust timing
4. Validate Data Consistency: Check that terminated employees are filtered
5. Test Edge Cases: Empty departments, users without managers, custom fields

Security Considerations

• Never commit API keys: Use environment variables or secret management
• Rotate keys regularly: Every 90 days minimum
• Monitor usage: Check API logs for unusual patterns
• Limit scope: Create separate keys for different integrations
• Audit trail: BambooHR logs all API access - review regularly

Next Steps

With your API key configured:

1. Map BambooHR's data model to your internal schema
2. Implement incremental sync using the lastChanged parameter
3. Set up error handling for common failures (rate limits, network issues)
4. Build monitoring for data freshness and API health

For production deployments managing multiple HRIS integrations, consider using a unified API platform like Apideck to normalize data models and handle authentication complexity across different systems.

Conclusion

Getting BambooHR API keys takes 30 seconds. Building a robust integration that handles permissions, rate limits, and data consistency takes proper planning. Whether you integrate directly or through a unified API, understanding BambooHR's permission model and rate limits is crucial for reliable HR data synchronization.