Skip to content
Tallyfy

BambooHR technical integration

Connecting BambooHR to Tallyfy

Section titled “Connecting BambooHR to Tallyfy”

Connect BambooHR to Tallyfy and your HR events can start the right process on their own. Hire someone, and Tallyfy kicks off an onboarding run. Change their job, and it starts a role-change run. When they leave, it handles offboarding. Tallyfy pulls the person’s details straight from BambooHR, so no one re-types names, emails, or start dates. (For the plain overview, see the BambooHR integration page.)

You can set this up three ways: have your system call BambooHR’s API directly, listen for BambooHR’s webhooks1, or check for changes on a schedule. Rather not write code? No-code tools like Zapier, Make, Merge, and Finch can connect the two for you.

For developers

Section titled “For developers”

(Skip this unless you’re setting up the technical side.)

REST API integration

Section titled “REST API integration”

Fetch employee data from BambooHR, then launch a Tallyfy process with that data:

const handleBambooHREmployee = async (employeeId) => {
  // Fetch employee from BambooHR
  const employee = await fetch(
    `https://api.bamboohr.com/api/gateway.php/${subdomain}/v1/employees/${employeeId}`,
    {
      headers: {
        'Authorization': `Basic ${Buffer.from(apiKey + ':x').toString('base64')}`,
        'Accept': 'application/json'
      }
    }
  ).then(res => res.json());


  // Launch a Tallyfy process (run) for this employee
  const run = await fetch(
    `https://go.tallyfy.com/api/organizations/${orgId}/runs`,
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_TALLYFY_TOKEN',
        'X-Tallyfy-Client': 'APIClient',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        checklist_id: 'your_onboarding_template_id',
        name: `Onboarding - ${employee.firstName} ${employee.lastName}`,
        data: {
          employee_id: employee.id,
          full_name: `${employee.firstName} ${employee.lastName}`,
          email: employee.workEmail,
          department: employee.department,
          location: employee.location,
          job_title: employee.jobTitle,
          manager: employee.supervisor,
          start_date: employee.hireDate
        }
      })
    }
  );


  return run.json();
};

Webhook integration

Section titled “Webhook integration”

BambooHR webhooks use SHA-256 HMAC signatures. You’ll need to verify every incoming request before processing it:

const express = require('express');
const crypto = require('crypto');
const app = express();


app.post('/bamboohr-webhook', express.raw({ type: '*/*' }), async (req, res) => {
  const signature = req.headers['x-bamboohr-signature'];
  const expected = crypto
    .createHmac('sha256', process.env.BAMBOOHR_WEBHOOK_SECRET)
    .update(req.body)
    .digest('hex');


  if (signature !== expected) {
    return res.status(401).send('Invalid signature');
  }


  const { type, employees } = JSON.parse(req.body);


  for (const employeeId of employees) {
    switch (type) {
      case 'employee':
        await launchOnboardingWorkflow(employeeId);
        break;
      case 'job_information':
        await launchRoleChangeWorkflow(employeeId);
        break;
      case 'employment_status':
        await handleStatusChange(employeeId);
        break;
    }
  }


  res.status(200).send('OK');
});

Polling for changes

Section titled “Polling for changes”

If your system can’t receive webhooks, BambooHR supports change reports you can poll on a schedule:

const pollBambooHRChanges = async () => {
  const since = new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString();


  const changes = await fetch(
    `https://api.bamboohr.com/api/gateway.php/${subdomain}/v1/employees/changed?since=${since}`,
    {
      headers: {
        'Authorization': `Basic ${Buffer.from(apiKey + ':x').toString('base64')}`,
        'Accept': 'application/json'
      }
    }
  ).then(res => res.json());


  for (const employee of changes.employees) {
    await processEmployeeChange(employee.id, employee.action);
  }
};

Data mapping

Section titled “Data mapping”

Common BambooHR fields mapped to Tallyfy form field variables:

BambooHR fieldTallyfy variableNotes
idemployee_idRecord ID
firstName + lastNamefull_nameCombined name
workEmailemailWork email
departmentdepartmentDepartment
divisiondivisionDivision
locationlocationWork location
jobTitlejob_titleTitle
supervisormanagerDirect manager name
supervisorEmailmanager_emailManager’s email
hireDatestart_dateHire date
employmentHistoryStatusstatusEmployment status

Authentication

Section titled “Authentication”

BambooHR uses HTTP Basic auth - the API key is the username and x is the password:

const getBambooHRHeaders = () => ({
  'Authorization': `Basic ${Buffer.from(process.env.BAMBOOHR_API_KEY + ':x').toString('base64')}`,
  'Accept': 'application/json'
});

Webhook events

Section titled “Webhook events”

BambooHR webhooks can fire on these field changes:

  • Employee created - new employee added
  • Job information - title, department, or location changed
  • Employment status - active, terminated, or on leave
  • Compensation - salary or pay rate changed
  • Time off - requests or balances changed

iPaaS alternatives

Section titled “iPaaS alternatives”

If you’d rather not build a direct API integration:

  • Merge API - unified HRIS API that includes BambooHR
  • Finch - employment system API
  • Zapier - pre-built BambooHR triggers and actions
  • Make - visual workflow builder with a BambooHR connector
Section titled “Related articles”

Vendors > BambooHR

Tallyfy extends BambooHR beyond basic HR admin by launching cross-department workflows for…

Footnotes

Section titled “Footnotes”

  1. Webhooks are automatic messages BambooHR sends to your system the moment something changes, so you don’t have to keep asking. ↩

Get in touch
About Tallyfy