The ServiceNow BambooHR integration enables organizations to synchronize employee data from BambooHR into ServiceNow HR Service Delivery (HRSD), automatically triggering onboarding workflows and maintaining accurate organizational charts. This integration eliminates manual data entry, reduces errors, and ensures that ServiceNow always reflects the current state of your workforce as managed in BambooHR. The integration primarily flows data from BambooHR to ServiceNow using REST API calls, with scheduled imports handling employee records, organizational structure updates, and new hire events that trigger HRSD onboarding cases. The integration leverages ServiceNow's Integration Hub and operates within the HR Service Delivery application, utilizing Connection & Credential Aliases for secure API authentication and Flow Designer for orchestrating data synchronization workflows.
Prerequisites
- •ServiceNow San Diego or later with HR Service Delivery application installed
- •Integration Hub Professional license or higher
- •BambooHR administrator access with API key generation permissions
- •ServiceNow admin role or integration_admin role for credential management
- •HRSD Case Management plugin (com.sn_hr_case) activated
- •Employee Relations plugin (com.sn_employee_relations) for org chart functionality
- •MID Server configured if BambooHR instance requires IP whitelisting
Architecture Overview
The integration uses ServiceNow's Integration Hub with custom REST integrations rather than a dedicated spoke, as no official BambooHR spoke exists in the ServiceNow Store. Authentication is established using BambooHR API keys stored in ServiceNow Connection & Credential Aliases, with outbound REST calls made via RESTMessageV2 or Flow Designer REST steps. Data flows unidirectionally from BambooHR to ServiceNow, triggered by scheduled flows that poll the BambooHR REST API for changes or run on fixed intervals to sync employee data. A MID Server is not typically required unless your BambooHR instance has IP restrictions, as the integration uses standard HTTPS outbound calls. BambooHR enforces rate limiting at 1000 requests per hour per API key, requiring careful orchestration of bulk data imports and consideration of pagination for large employee datasets.
Sourdough: ServiceNow Monitoring and Analytics
A Chrome extension for ServiceNow Admins and Developers with essential tools, analytics, graphs and monitoring features.
Free to install. Pro $5/month after a 14-day no-card trial.
Pro requires the ServiceNow admin role. Upgrade inside the extension.
Implementation Steps
Generate BambooHR API key and configure ServiceNow credential
In BambooHR, navigate to Settings > API Keys and generate a new API key with read permissions for employee data. Copy the generated API key and your BambooHR subdomain name (e.g., yourcompany.bamboohr.com). In ServiceNow, navigate to Connections & Credentials > Credentials and create a new API Key credential. Set the Name field to 'BambooHR API Credential' and paste your API key in the API Key field, leaving username blank as BambooHR uses key-only authentication.
Create BambooHR Connection and Credential Alias
Navigate to Connections & Credentials > Connection & Credential Aliases and create a new alias named 'BambooHR Connection'. Set the Connection URL to 'https://api.bamboohr.com/api/gateway.php/yourcompany' replacing 'yourcompany' with your actual BambooHR subdomain. Select the credential created in step 1 for the Credential field and test the connection to verify authentication. Configure the connection timeout to 30 seconds to handle potentially slow BambooHR API responses during bulk data operations.
Create REST Message for BambooHR API endpoints
Navigate to System Web Services > Outbound > REST Message and create a new REST Message named 'BambooHR Employee API'. Set the Endpoint to the Connection Alias created in step 2 and configure default HTTP headers including 'Accept: application/json' and 'Content-Type: application/json'. Create HTTP Methods for key endpoints: 'getEmployees' with endpoint '/v1/employees/directory', 'getEmployee' with endpoint '/v1/employees/${employee_id}', and 'getOrgChart' with endpoint '/v1/employees/directory'. Test each method to ensure proper authentication and response formatting.
// Test the REST Message connection
var rm = new sn_ws.RESTMessageV2('BambooHR Employee API', 'getEmployees');
rm.setStringParameterNoEscape('employee_id', '1234');
var response = rm.execute();
var responseBody = response.getBody();
gs.info('BambooHR Response: ' + responseBody);
var httpStatus = response.getStatusCode();
gs.info('HTTP Status: ' + httpStatus);Configure Flow Designer for employee data synchronization
Navigate to Process Automation > Flow Designer and create a new flow named 'BambooHR Employee Sync'. Add a Schedule trigger set to run daily at 2 AM to avoid peak business hours. Configure a REST step using the BambooHR REST Message to fetch employee directory data, then add a For Each loop to process individual employee records. Within the loop, add a Look up Record step to check if an HRSD Person record exists, followed by conditional Insert or Update Record steps to maintain employee data synchronization.
// Script step within Flow Designer to parse BambooHR employee data
(function execute(inputs, outputs) {
var bambooEmployee = JSON.parse(inputs.employee_data);
outputs.employee_number = bambooEmployee.id;
outputs.first_name = bambooEmployee.firstName;
outputs.last_name = bambooEmployee.lastName;
outputs.email = bambooEmployee.workEmail;
outputs.department = bambooEmployee.department;
outputs.job_title = bambooEmployee.jobTitle;
outputs.manager_id = bambooEmployee.supervisor;
outputs.hire_date = bambooEmployee.hireDate;
})(inputs, outputs);Setup new hire detection and onboarding trigger
Create a second flow named 'BambooHR New Hire Detection' with a schedule trigger running every 2 hours during business days. Configure the flow to query BambooHR for employees hired within the last 48 hours using the hire date filter parameter. Add conditional logic to check if an HRSD onboarding case already exists for each new hire using the employee ID. When a new hire is detected without an existing case, trigger the HRSD onboarding process by creating a new HR Case record with case type 'Onboarding' and assigned to the appropriate HR team.
// Create HRSD onboarding case for new hire
var hrCase = new GlideRecord('sn_hr_core_case');
hrCase.initialize();
hrCase.short_description = 'Onboarding: ' + inputs.first_name + ' ' + inputs.last_name;
hrCase.state = 'open';
hrCase.category = 'onboarding';
hrCase.subject_person = inputs.person_sys_id;
hrCase.opened_for = inputs.person_sys_id;
hrCase.assignment_group = 'HR Onboarding Team';
hrCase.priority = '3';
var caseId = hrCase.insert();
gs.info('Created onboarding case: ' + caseId);Implement organizational chart synchronization
Navigate to Flow Designer and create a flow named 'BambooHR Org Chart Sync' with a weekly schedule trigger. Configure REST steps to fetch the complete employee directory from BambooHR including manager relationships and department structures. Add script steps to build the hierarchical relationships by matching supervisor IDs to employee records and updating the manager field in HRSD Person records. Include error handling for orphaned manager references and departments that may not exist in ServiceNow, creating placeholder department records as needed.
// Update manager relationships from BambooHR data
(function execute(inputs, outputs) {
var employeeGR = new GlideRecord('sys_user');
if (employeeGR.get('employee_number', inputs.employee_id)) {
if (inputs.manager_id && inputs.manager_id != '') {
var managerGR = new GlideRecord('sys_user');
if (managerGR.get('employee_number', inputs.manager_id)) {
employeeGR.manager = managerGR.sys_id;
employeeGR.update();
gs.info('Updated manager for employee: ' + inputs.employee_id);
}
}
}
})(inputs, outputs);Configure error handling and logging
Add comprehensive error handling to all flows by implementing Try-Catch subflows around REST API calls and database operations. Configure Flow Designer to log detailed error messages to the System Log with source 'BambooHR Integration' for easy troubleshooting. Set up email notifications to integration administrators when critical errors occur, such as authentication failures or complete sync failures. Create a custom table 'u_bamboohr_sync_log' to track sync statistics including records processed, errors encountered, and execution times for monitoring integration health over time.
// Error handling script for BambooHR integration flows
(function execute(inputs, outputs) {
try {
// REST call logic here
var response = rm.execute();
if (response.getStatusCode() != 200) {
throw 'BambooHR API returned status: ' + response.getStatusCode();
}
outputs.success = true;
} catch (error) {
gs.error('BambooHR Integration Error: ' + error, 'BambooHR Integration');
gs.eventQueue('bamboohr.sync.error', null, error.toString(), gs.getUserID());
outputs.success = false;
outputs.error_message = error.toString();
}
})(inputs, outputs);Test integration and validate data synchronization
Execute each flow manually from Flow Designer to verify proper functionality and data mapping accuracy. Compare a sample of employee records between BambooHR and ServiceNow to ensure all required fields are correctly synchronized and manager relationships are properly established. Test the new hire detection by creating a test employee in BambooHR with a recent hire date and verifying that an HRSD onboarding case is automatically created. Monitor the System Log during test runs to identify any authentication issues, data mapping errors, or performance concerns that need addressing before production deployment.
// Validation script to compare BambooHR and ServiceNow data
var validation = new GlideRecord('sys_user');
validation.addQuery('employee_number', '!=', '');
validation.addQuery('active', true);
validation.query();
var mismatchCount = 0;
while (validation.next()) {
// Call BambooHR API to get current employee data
var rm = new sn_ws.RESTMessageV2('BambooHR Employee API', 'getEmployee');
rm.setStringParameterNoEscape('employee_id', validation.employee_number.toString());
var response = rm.execute();
if (response.getStatusCode() == 200) {
var bambooData = JSON.parse(response.getBody());
if (bambooData.workEmail != validation.email.toString()) {
gs.warn('Email mismatch for employee: ' + validation.employee_number);
mismatchCount++;
}
}
}
gs.info('Data validation complete. Mismatches found: ' + mismatchCount);Common Use Cases
Automated new hire onboarding workflow
When a new employee is added to BambooHR with a hire date within the next 30 days, the integration automatically creates an HRSD onboarding case assigned to the HR team. The case includes all employee details from BambooHR and triggers sub-tasks for equipment provisioning, access requests, and orientation scheduling. This eliminates manual case creation and ensures consistent onboarding processes for every new hire.
Daily employee data synchronization
A scheduled flow runs daily to synchronize employee changes from BambooHR to ServiceNow, updating contact information, job titles, departments, and manager assignments in HRSD Person records. The sync identifies terminated employees and marks their ServiceNow user accounts as inactive while preserving historical data. This ensures ServiceNow always reflects current organizational structure and employee status for accurate service delivery.
Manager hierarchy updates for org chart
Weekly synchronization of organizational structure from BambooHR updates manager relationships in ServiceNow, enabling accurate org charts in HRSD and proper case assignment routing. The integration handles complex scenarios like manager changes, department transfers, and temporary reporting relationships. This ensures HR cases are automatically assigned to the correct managers and approval workflows follow the current organizational structure.
Department and cost center synchronization
The integration synchronizes department structures and cost center information from BambooHR to maintain accurate organizational units in ServiceNow for reporting and case categorization. When new departments are created in BambooHR, corresponding department records are automatically created in ServiceNow with proper hierarchy relationships. This supports accurate HR analytics and ensures service catalog items can be properly categorized by organizational unit.
Employee lifecycle event triggers
Integration monitors BambooHR for status changes like promotions, transfers, or terminations and automatically triggers appropriate HRSD workflows in ServiceNow. Promotions trigger access review cases, transfers initiate workspace change requests, and terminations launch offboarding workflows with tasks for IT, facilities, and HR teams. This ensures no lifecycle events are missed and all necessary actions are completed consistently.
Troubleshooting
401 Unauthorized errors when calling BambooHR API
Check that the API key in your ServiceNow credential is current and has not expired in BambooHR. Navigate to BambooHR Settings > API Keys to verify the key status and regenerate if necessary. In ServiceNow, update the credential record with the new API key and test the connection from the Connection & Credential Alias. Verify that the API key has the required permissions for employee data access in BambooHR.
Rate limit exceeded errors during bulk employee sync
BambooHR enforces a limit of 1000 API calls per hour, which can be exceeded during initial data loads or large organizational updates. Implement pagination in your flows to process employees in smaller batches and add wait steps between API calls to stay within rate limits. Check the Flow Designer execution history to identify which flows are consuming the most API calls and schedule them to run at different times to distribute the load throughout the day.
Duplicate employee records created in ServiceNow
This typically occurs when the employee matching logic fails to find existing records due to data format differences or missing employee numbers. Review your Flow Designer lookup conditions to ensure they are using consistent field formats and handle cases where employee numbers might be stored differently in BambooHR versus ServiceNow. Add data transformation steps to normalize employee IDs and implement duplicate prevention logic that checks multiple matching criteria like email address and full name.
Manager relationships not updating correctly
Manager hierarchy sync issues often result from processing employees before their managers are synchronized or when manager employee IDs don't match between systems. Modify your org chart sync flow to process employees in multiple passes, first creating all employee records, then updating manager relationships in a second pass. Add validation logic to verify manager employee IDs exist in ServiceNow before setting manager relationships and implement error logging for orphaned manager references.
New hire onboarding cases not triggering automatically
Check the hire date filtering logic in your new hire detection flow to ensure it correctly identifies employees within your specified timeframe. Verify that the BambooHR hire date format matches your ServiceNow date parsing logic and account for timezone differences between systems. Review the conditional logic that checks for existing onboarding cases to ensure it's not preventing legitimate case creation due to overly strict matching criteria.
Flow executions timing out during large data syncs
Large employee datasets can cause Flow Designer executions to exceed timeout limits, especially when processing hundreds of employees sequentially. Break large sync operations into smaller batches using subflows that process 50-100 employees at a time, triggered by parent flows with appropriate delays between batches. Consider moving bulk operations to scheduled script executions that have longer timeout limits and can handle larger datasets more efficiently than Flow Designer.
Pro Tips
- →Implement delta synchronization by storing the last sync timestamp in a system property and using BambooHR's lastChanged parameter to only fetch modified employee records, significantly reducing API calls and improving sync performance.
- →Create a custom table to track synchronization metadata including last sync times, error counts, and processed record counts for each integration flow, enabling proactive monitoring and performance optimization.
- →Use ServiceNow's Transform Map functionality for complex data transformations when importing BambooHR data, especially for handling department mappings and standardizing job titles across systems.
- →Configure Business Rules on the sys_user table to automatically update related HR records when employee data changes, ensuring consistency across all ServiceNow applications that reference employee information.
- →Set up Integration Hub Flow Analytics to monitor API response times and success rates, creating alerts when BambooHR API performance degrades or error rates exceed acceptable thresholds.
- →Implement field-level data validation in your flows to catch data quality issues early, such as invalid email formats or missing required fields, and route these exceptions to HR data stewards for manual review.
Known Limitations
- —BambooHR's REST API enforces a strict rate limit of 1000 requests per hour per API key, which can be problematic for organizations with large employee counts or frequent synchronization requirements. This may require careful scheduling and batching of sync operations.
- —The integration is unidirectional from BambooHR to ServiceNow, as BambooHR's API has limited write capabilities and updating employee records from ServiceNow back to BambooHR is not recommended due to data governance concerns.
- —BambooHR's API does not support real-time webhooks for employee changes, requiring polling-based synchronization that introduces latency between data changes in BambooHR and updates in ServiceNow, typically 2-24 hours depending on sync schedules.
- —Custom fields in BambooHR may require additional API calls to retrieve, as they are not included in the standard employee directory endpoint, potentially increasing the number of API calls needed for complete employee profiles.
- —Historical employee data and audit trails from BambooHR are not easily synchronized to ServiceNow, as the API focuses on current employee status rather than change history, limiting the ability to track employee lifecycle events over time.
Frequently Asked Questions
Can I sync employee data in real-time from BambooHR to ServiceNow?
BambooHR does not support webhooks or real-time notifications for employee changes, so the integration relies on scheduled polling of their REST API. The fastest practical sync frequency is every 30 minutes due to API rate limits, but most organizations run employee syncs daily or weekly. For truly time-sensitive updates like new hires, you can configure more frequent polling during business hours while running less frequent syncs overnight.
Does ServiceNow have an official Integration Hub spoke for BambooHR?
No, ServiceNow does not provide an official BambooHR spoke in the Integration Hub catalog as of the current release. The integration must be built using custom REST Message records and Flow Designer workflows that directly call the BambooHR REST API. This provides more flexibility in customizing the integration but requires more manual configuration compared to official spokes. Monitor the ServiceNow Store for potential third-party BambooHR spokes from certified partners.
How do I handle employees who exist in ServiceNow but not in BambooHR?
This scenario typically occurs with contractors, vendors, or employees in different HR systems. Create exception handling logic in your sync flows that identifies ServiceNow users without corresponding BambooHR records and flags them for manual review. You can maintain a custom table of sync exceptions or add a field to user records indicating their data source. Avoid automatically deactivating these accounts, as they may be legitimate non-BambooHR users who need ServiceNow access.
What happens if the BambooHR API key expires or is rotated?
API key expiration will cause all integration flows to fail with 401 authentication errors. Implement monitoring and alerting by checking for authentication failures in your flows and sending notifications to integration administrators. When rotating API keys, update the ServiceNow credential record immediately and test all flows to ensure continuity. Consider creating a backup API key in BambooHR and storing it in a secondary credential for emergency failover scenarios.
Can I customize which BambooHR fields are synchronized to ServiceNow?
Yes, you can fully customize field mappings in your Flow Designer scripts and Transform Maps to select only the BambooHR fields your organization needs. The BambooHR API allows you to specify which fields to retrieve in each call, reducing payload size and improving performance. Create a field mapping configuration table in ServiceNow to make field selections configurable without modifying flows, and document any custom field mappings for future maintenance.
How do I test the integration without affecting production employee data?
Create a dedicated BambooHR sandbox environment if available, or use a separate ServiceNow sub-production instance for testing. Configure test flows that target a specific department or small group of test employees using BambooHR's filtering capabilities. Use ServiceNow's clone data preserves to copy production configurations to development instances, then modify the Connection Alias to point to test endpoints. Always test with a small dataset first before enabling full production synchronization.
What's the best practice for handling employee terminations and departures?
Configure your sync flow to detect terminated employees by monitoring status changes in BambooHR and automatically trigger HRSD offboarding cases in ServiceNow. Set terminated employees' ServiceNow accounts to inactive rather than deleting them to preserve historical data and case assignments. Create automated tasks for IT access removal, equipment return, and exit interviews. Use Business Rules to cascade the termination status to related records like asset assignments and group memberships while maintaining audit trails.
Test Your Knowledge
Quick 3-question quiz — see how your ServiceNow skills stack up.
A list view on a table with millions of records is slow. Best fix?
Select an answer to continue