BambooHR API Essential Guide

What type of API does BambooHR provide?

BambooHR uses a RESTful API. Here are the key points about BambooHR's API:

API Type

BambooHR utilizes a RESTful API. This means it follows REST (Representational State Transfer) principles for designing networked applications.

Key Characteristics

• It is a RESTful Internet protocol built around making semantically meaningful HTTPS requests to access or modify resources (usually employee data).
• The API can be used to manipulate employee data and generate reports in several formats.
• All requests must be sent over HTTPS.

Authentication

• Authentication is done using API keys.
• Each user can have one or more secret API keys that identify them to the API.
• API keys are sent over HTTP Basic Authentication, using the secret key as the username and any random string as the password.

Making Requests

• API requests are made to URLs beginning with: https://api.bamboohr.com/api/gateway.php/{company subdomain name}/.
• Requests should be in UTF-8 encoding.
• The API can throttle requests if they are deemed too frequent.

Best Practices

• Implementations should be prepared for 503 Service Unavailable responses due to throttling.
• They should also handle potential connection issues resulting in no HTTP response.
• Each employee has an immutable employee ID that is unique within a company, which can be used for referencing.

By using a RESTful API, BambooHR provides a standardized and widely-supported approach for integrating with their HR management system. This allows developers to easily access and manipulate employee data using familiar HTTP methods and conventions.

Does the BambooHR API have webhooks?

Webhook Support

Yes, the official BambooHR API does support webhooks.

Types of Events

BambooHR allows you to create webhooks to fire when changes are made to employees. You can specify which fields to monitor and what fields to POST to you when those changes occur.

Webhook Types

BambooHR supports two different types of webhooks:

1. Global Webhooks
2. Permissioned Webhooks

Monitored Fields

By default, a BambooHR user can specify which fields they want to monitor. The list of fields that can be monitored includes (but is not limited to):

• Address Line 1
• Address Line 2
• Birth Date
• City
• Compensation Change Reason
• Compensation: Date
• Country
• Department
• Division
• Employee #
• Employment Status
• Hire Date
• Job Title
• Pay rate
• Work Email
• And many more

Webhook Configuration

• Webhooks can be configured by an admin user in the Account Settings section.
• Users can specify a schedule for when they want webhooks to fire.
• They can also limit how often a webhook will fire by setting a maximum number of requests per interval in seconds.
• BambooHR will post to HTTPS URLs only; HTTP is not supported.

Security

• BambooHR recommends using a private secure key to ensure that a request comes from BambooHR.
• The webhook is secured using SHA-256 HMAC.
• When the webhook is triggered, BambooHR includes a timestamp header (X-BambooHR-Timestamp) and a SHA-256 HMAC signature (X-BambooHR-Signature).

API and Documentation

• The Webhook API is currently in public beta.
• BambooHR provides comprehensive API documentation for developers.

In summary, the BambooHR API offers robust webhook support, allowing users to monitor a wide range of employee-related events and receive notifications when changes occur.

Rate Limits and other limitations

Based on the search results provided, here are the key points regarding API rate limits for the BambooHR API:

Rate Limiting Information

1. BambooHR does have rate limits, but specific details are not easily found in the public documentation.

2. API requests can be throttled if BambooHR deems them to be too frequent. Implementations should always be prepared for a 503 Service Unavailable response.

3. When rate limiting occurs, a "Retry-After" header may be available in the response, indicating when it's appropriate to retry the request.

Key Points to Consider

1. There is no explicit mention of specific rate limit numbers (e.g., requests per second or per day) in the provided search results.

2. Developers are advised to contact BambooHR directly for more detailed information on their API rate limits.

3. The API uses HTTP status codes to indicate rate limiting and other issues:

   • 503 Unavailable: Often due to rate limiting
   • 429 Limit Exceeded: Indicates the account has reached its employee limit

4. Implementations should be prepared for general Internet packet loss resulting in broken connections with no HTTP response.

Best Practices

1. Always be prepared to handle 503 Service Unavailable responses in your implementation.

2. Implement proper error handling for various HTTP status codes, including those related to rate limiting and other potential issues.

3. Consider implementing a backoff strategy when encountering rate limit errors, using the "Retry-After" header when available.

4. If you need more specific information about rate limits for your use case, it's recommended to reach out to BambooHR support directly.

In summary, while BambooHR does implement API rate limiting, the specific details are not publicly available. Developers should design their applications to handle potential rate limiting responses and contact BambooHR directly for more detailed information on rate limits if needed for their specific use case.

Latest API Version

The most recent version of the BambooHR API is V1. Here are the key points about the BambooHR API:

Current Version

The current version of the BambooHR API is V1 [1]. There is no mention of a more recent version in the provided search results.

API Details

• The BambooHR API is a RESTful protocol that uses HTTPS requests to access or modify employee data [1].
• It can be used to manipulate employee data and generate reports in several formats [1].
• All API requests must be sent over HTTPS [2].

Authentication

• API requests are authenticated using an API key [1].
• The API key is sent over HTTP Basic Authentication, using the secret key as the username and any random string as the password [1].
• Users can generate an API key by logging into their BambooHR account and accessing the "API Keys" option in their user menu [1].

Making Requests

• API requests are made to a URL that begins with https://api.bamboohr.com/api/gateway.php/{company subdomain name}/ [2].
• All requests should be in UTF-8 [2].

JSON Support

• As of 2018, all endpoints that previously accepted only XML now also accept JSON [3].
• To use JSON, specify "Content-Type: application/json" in the request header [3].

Recent Updates

• In 2022, beta developer webhooks were introduced for API users [3].
• In 2023, the creation process for API aliases for custom fields was updated to use only alphanumeric characters, making them more usable in API integrations [3].

Best Practices

• Implementations should be prepared for potential 503 Service Unavailable responses due to throttling [2].
• API consumers should ignore any XML tags and attributes they do not recognize to maintain forward compatibility [2].

While the API has undergone various updates and improvements over the years, the core version remains V1. BambooHR has stated that if a major API change becomes necessary, they will create a new major version number and communicate the change to their partners [2].

How to get a BambooHR developer account and API Keys?

1. Obtain a BambooHR Account

• You need to have an existing BambooHR account for your company. If you don't have one, you'll need to sign up for BambooHR first.

2. Get API Access

• Log into your BambooHR account with administrator permissions.
• Click on your name in the upper right-hand corner to access the user context menu.
• Look for the "API Keys" option in that menu. If you don't see it, you may need to contact BambooHR support to enable API access for your account.

3. Generate an API Key

• On the API Keys page, enter a name for your API key in the "API Key Name" field.
• Click "Generate Key" to create a new API key.
• The API key will be displayed. Make sure to copy and securely store this key, as it will not be shown again.

4. Use the API Key for Authentication

• Use the generated API key as the username in HTTP Basic Authentication when making API requests.
• The API key should be sent as the username, with any random string as the password (commonly "x").

5. Make API Requests

• API requests should be made to the URL: https://api.bamboohr.com/api/gateway.php/{subdomain}/v1/ where {subdomain} is your company's BambooHR subdomain.
• All requests must be sent over HTTPS.
• Use UTF-8 encoding for all requests.

What can you do with the BambooHR API?

Based on the search results, here are the key data models you can interact with using the BambooHR API:

Employee Data

• Access and update individual employee records
• Retrieve bulk employee data through custom reports
• Query specific employee fields like name, birthday, etc.
• Access employee files

Key points:

• Use endpoint /v1/employees/{id}/ for individual employees
• Use custom reports endpoint for bulk data retrieval
• Can specify fields to retrieve in API requests

Company Data

• Access company files and reports

Time Off and Benefits

• Manage time off requests and balances
• Access benefits information

Time Tracking

• Access time tracking data

Goals and Performance

• Manage employee goals and performance data

Training

• Access training-related data

Other Data Models

• Recruitment data
• Onboarding information
• Payroll data
• Employee satisfaction metrics

Key capabilities:

• Read and write access to most data models
• Generate reports in multiple formats
• Authentication and permissions control access

The API allows interacting with most core HR data in BambooHR, with the ability to both retrieve and update information programmatically. Custom reports provide a flexible way to access bulk data across different models.