API Data Provider - Online Help

Connecting to BambooHR

BambooHR supports both API key (token) and OAuth 2.0 authentication to control access to the API.

Using Token Authentication

In order to authenticate to BambooHR, you'll need to provide your API Key. To generate an API key, you should log in and click your 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 Keys" option in that menu to go to the page, where you can create a new API Key. Additionally, you will need to set the Domain, found in the domain name of your BambooHR account. For example if your BambooHR account is acmeinc.bamboohr.com, then the Domain should be 'acmeinc'. Set both the API Key and Domain in the ProfileSettings property to connect.

Example connection string

Profile=C:\profiles\BambooHR.apip;ProfileSettings='Domain=acmeinc;APIKey=your_api_key';

Using OAuth Authentication

BambooHR also supports OAuth 2.0 authentication. You will first need to register an OAuth application with BambooHR. This can be done from the BambooHR Developer Portal at https://developers.bamboohr.com, where you can create an application to obtain a client ID and client secret. When registering the application, set the Redirect URI to match the CallbackURL you intend to use. Additionally, you will need to set the Domain, found in the domain name of your BambooHR account. For example if your BambooHR account is acmeinc.bamboohr.com, then the Domain should be 'acmeinc'.

After setting the following in the connection string, you are ready to connect:

  • AuthScheme: Set this to OAuth.
  • InitiateOAuth: Set this to GETANDREFRESH. You can use InitiateOAuth to manage the process to obtain the OAuthAccessToken.
  • OAuthClientId: Set this to the client ID that is specified in your app settings.
  • OAuthClientSecret: Set this to the client secret that is specified in your app settings.
  • CallbackURL: Set this to the Redirect URI you specified in your app settings.
  • Domain: Set this in the ProfileSettings to your BambooHR domain.
  • Scope: Optional. Set this to the space-separated list of scopes to request when authenticating. Defaults to openid email offline_access employee_directory. The offline_access scope is required to obtain a refresh token, and the employee_directory scope is required to retrieve employee records.

Example connection string

Profile=C:\profiles\BambooHR.apip;ProfileSettings='Domain=acmeinc';AuthScheme=OAuth;InitiateOAuth=GETANDREFRESH;OAuthClientId=your_client_id;OAuthClientSecret=your_client_secret;CallbackURL=your_callback_url;

Important Notes

  • To establish a successful test connection, the employee_directory permission must be enabled. If using OAuth authentication, enable the employee_directory scope when registering the application. If using API Key authentication, enable the employee_directory permission under Settings > Access Levels.
  • (OAuth only) To obtain a refresh token, the offline_access scope must be enabled when registering the application and included in the Scope connection property when authenticating.

Available Tables

The BambooHR API Profile provides access to the following tables:

  • BenefitCoverages: Returns benefit coverages.
  • BenefitDeductionTypes: Returns benefit deduction types.
  • BenefitGroupEmployees: Returns benefit group employees.
  • BenefitGroupPlanCosts: Returns benefit group plan costs.
  • BenefitGroupPlans: Returns benefit group plans.
  • BenefitGroups: Returns benefit groups.
  • BenefitPlanCoverages: Returns benefit plan coverages.
  • BenefitPlans: Returns benefit plans.
  • CompanyCategories: Lists company files and categories.
  • EmployeeBenefitDeductions: Returns benefit deductions for a given employee.
  • EmployeeBenefitPlanDeductions: Returns benefit plan deductions for a given employee.
  • EmployeeCategories: Lists employee files and categories.
  • EmployeeDeductions: Returns employee deductions by benefit plan.
  • EmployeeDependents: Returns all employee dependents.
  • EmployeeDirectDepositAccounts: Returns an employee's direct deposit information.
  • EmployeeTimeOffCalculator: Returns time off balances for a given employee.
  • EmployeeTimeOffPolicies: Returns time off policies for a given employee.
  • EmployeeUnpaidPaystubs: Returns an employee's unpaid paystubs.
  • EmployeeWithholdings: Returns an employee's default withholdings.
  • Employees: Gets employee directory.
  • Hours: Returns an hour record for a given time tracking ID.
  • TimeOffPolicies: Returns a list of time off policies.
  • TimeOffRequests: Returns a list of time off requests.
  • TimeOffTypes: Returns a list of time off types.
  • TimeSheets: Returns timesheet entries for a given period of time defined by the startDate and endDate filters.
  • Whosout: Returns a list, sorted by date, of employees who will be out, and company holidays, for a period of time.

Usage Examples

BenefitCoverages: 

SELECT * FROM BenefitCoverages

BenefitDeductionTypes: 

SELECT * FROM BenefitDeductionTypes

BenefitGroupEmployees: 

SELECT * FROM BenefitGroupEmployees

BenefitGroupPlanCosts: 

SELECT * FROM BenefitGroupPlanCosts

BenefitGroupPlans: 

SELECT * FROM BenefitGroupPlans

BenefitGroups: 

SELECT * FROM BenefitGroups

BenefitPlanCoverages: 

SELECT * FROM BenefitPlanCoverages

BenefitPlans: 

SELECT * FROM BenefitPlans

CompanyCategories: 

SELECT * FROM CompanyCategories

EmployeeBenefitDeductions: 

SELECT * FROM EmployeeBenefitDeductions WHERE EmployeeId = '123'

EmployeeBenefitPlanDeductions: 

SELECT * FROM EmployeeBenefitPlanDeductions WHERE EmployeeId = '123'

EmployeeCategories: 

SELECT * FROM EmployeeCategories WHERE EmployeeId = '123'

EmployeeDeductions: 

SELECT * FROM EmployeeDeductions WHERE BenefitPlanId = '123'

EmployeeDependents: 

SELECT * FROM EmployeeDependents WHERE EmployeeId = '123'

INSERT INTO EmployeeDependents (EmployeeId, FirstName, LastName, MiddleName, Relationship, DateOfBirth, AddressLine1, AddressLine2, City, State, ZipCode, Country, Gender, HomePhone, IsStudent, IsUsCitizen, MaskedSIN, MaskedSSN) VALUES ('4', 'John', 'Doe', 'A', 'child', '2010-05-15', '123 Main St', 'Apt 4B', 'Raleigh', 'NC', '27601', 'US', 'Male', '555-123-4567', 'yes', 'yes', '123-456-789', '123-45-6789')

UPDATE EmployeeDependents SET EmployeeId = '123', FirstName = 'John', LastName = 'Doe', MiddleName = 'A', Relationship = 'child', DateOfBirth = '2010-05-15', AddressLine1 = '123 Main St', AddressLine2 = 'Apt 4B', City = 'Raleigh', State = 'NC', ZipCode = '27601', Country = 'US', Gender = 'Male', HomePhone = '555-123-4567', IsStudent = 'no', IsUsCitizen = 'no', MaskedSIN = '123-456-789', MaskedSSN = '123-45-6789' WHERE Id = 'dependent-id'

EmployeeDirectDepositAccounts: 

SELECT * FROM EmployeeDirectDepositAccounts WHERE EmployeeId = '123'

EmployeeTimeOffCalculator: 

SELECT * FROM EmployeeTimeOffCalculator WHERE EmployeeId = '123'

EmployeeTimeOffPolicies: 

SELECT * FROM EmployeeTimeOffPolicies WHERE EmployeeId = '123'

EmployeeUnpaidPaystubs: 

SELECT * FROM EmployeeUnpaidPaystubs WHERE EmployeeId = '123'

EmployeeWithholdings: 

SELECT * FROM EmployeeWithholdings WHERE EmployeeId = '123'

Employees: 

SELECT * FROM Employees

Hours: 

SELECT * FROM Hours WHERE timeTrackingId = '123'

INSERT INTO Hours (timeTrackingId, employeeId, dateHoursWorked, rateType, hoursWorked, divisionId, departmentId, jobTitleId, payCode, payRate, jobCode, jobData) VALUES ('abc-123', '123', '2024-06-01', 'REG', '8', '1', '2', '3', 'HOURLY', '15.00', '100', 'JOB-001')

UPDATE Hours SET hoursWorked = '7.5', projectId = '10', taskId = '20', shiftDifferentialId = '5', holidayId = '2' WHERE timeTrackingId = 'abc-123'

DELETE FROM Hours WHERE timeTrackingId = 'abc-123'

TimeOffPolicies: 

SELECT * FROM TimeOffPolicies

TimeOffRequests: 

SELECT * FROM TimeOffRequests WHERE StartDate = '2024-01-01' AND EndDate = '2024-12-31'

INSERT INTO TimeOffRequests (EmployeeId, Start, End, Status, TypeId, AmountAmount) VALUES ('123', '2024-06-01', '2024-06-05', 'requested', '1', '4')

TimeOffTypes: 

SELECT * FROM TimeOffTypes

TimeSheets: 

SELECT * FROM TimeSheets WHERE startDate = '2024-01-01' AND endDate = '2024-12-31'

Whosout: 

SELECT * FROM Whosout

Connection Properties

The connection string properties are the various options that can be used to establish a connection. This section provides a complete list of the options you can configure in the connection string for this provider.

Property Description
APIKey Your BambooHR API Key.
AuthScheme The scheme used for authentication. Accepted entries are APIKey, OAuth, or None.
Allowed values are: BASIC, NONE, NTLM, OAUTH, APIKEY, OAUTH_CLIENT, OAUTH_PASSWORD
CallbackURL Identifies the URL users return to after authenticating to API via OAuth (Custom OAuth applications only).
Domain The Domain for the BambooHR account.
InitiateOAuth Specifies the process for obtaining or refreshing the OAuth access token, which maintains user access while an authenticated, authorized user is working.
Allowed values are: OFF, REFRESH, GETANDREFRESH
OAuthAccessToken Specifies the OAuth access token used to authenticate requests to the data source. This token is issued by the authorization server after a successful OAuth exchange.
OAuthClientId Specifies the client ID (also known as the consumer key) assigned to your custom OAuth application. This ID is required to identify the application to the OAuth authorization server during authentication.
OAuthClientSecret Specifies the client secret assigned to your custom OAuth application. This confidential value is used to authenticate the application to the OAuth authorization server. (Custom OAuth applications only.).
OAuthExpiresIn Specifies the duration in seconds, of an OAuth Access Token's lifetime. The token can be reissued to keep access alive as long as the user keeps working.
OAuthRefreshToken Specifies the OAuth refresh token used to request a new access token after the original has expired.
OAuthSettingsLocation Specifies the location of the settings file where OAuth values are saved.
OAuthTokenTimestamp Displays a Unix epoch timestamp in milliseconds that shows how long ago the current access token was created.
OAuthVerifier Specifies a verifier code returned from the OAuthAuthorizationURL . Used when authenticating to OAuth on a headless server, where a browser can't be launched. Requires both OAuthSettingsLocation and OAuthVerifier to be set.
Scope The OAuth scope(s) to request when authenticating to the BambooHR API, which must include employee_directory to allow access to employee data.

Copyright (c) 2026 CData Software, Inc. - All rights reserved.
Build 26.0.9770.0