Skip to content
Tallyfy

Paylocity technical integration

Integration options

Paylocity offers REST APIs through their developer program. Pick the approach that fits your partnership status and technical needs.

REST API integration

Use Paylocity’s REST API to trigger Tallyfy processes when employee events happen:

const handlePaylocityEvent = async (event) => {
  if (event.eventType === 'employee.created') {
    const employee = await paylocityAPI.get(
      `/v2/companies/${companyId}/employees/${event.employeeId}`
    );


    // Launch a Tallyfy process (called a "run") from a template
    const run = await fetch(
      `https://go.tallyfy.com/api/organizations/${orgId}/runs`,
      {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${tallyfyToken}`,
          'X-Tallyfy-Client': 'APIClient',
          'Accept': 'application/json',
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          checklist_id: 'f7e6d5c4b3a2918070615243342516f0',
          name: `Onboarding - ${employee.firstName} ${employee.lastName}`,
          // prerun keys are the kick-off fields' timeline IDs, not their labels
          prerun: {
            'a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6': employee.employeeId,      // Employee ID
            '3c9d1e7fa4b820516d8e2f7a9c0b4d15': `${employee.firstName} ${employee.lastName}`, // Full name
            '9f2b7c1e4a6d8035b1c7e9d2f4a6b801': employee.workEmail,       // Email
            '6e4a2c80f19b3d75e0a8c246b93f157d': employee.departmentCode,  // Department
            '2d7f9a1c5e3b806478d0a2c4e6f81b39': employee.workLocation,    // Location
            '5b8c0e2a7f4d1936a8e0c5b3d7f92146': employee.jobTitle,        // Job title
            '0a3e6b9d2c8f5174e9b2d6a0c4f83b57': `${employee.supervisorFirstName} ${employee.supervisorLastName}`, // Manager
            '7c1f4a8e0b3d69257a0e4c8b2f6d1930': employee.hireDate         // Start date
          }
        })
      }
    );


    return run.json();
  }
};

The prerun object is keyed by each kick-off field’s timeline ID, a 32-character hex string. You’ll find it as the id on each entry of the prerun array returned by GET /organizations/{org_id}/checklists/{checklist_id}. Don’t use the alias sitting next to it - alias keys never match, and Tallyfy drops unmatched keys silently, so the process launches successfully with that field left blank.

Webhook integration

Register webhooks to get real-time notifications from Paylocity:

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


app.post('/paylocity-webhook', express.json(), async (req, res) => {
  // Verify webhook signature
  const signature = req.headers['x-paylocity-signature'];
  const payload = JSON.stringify(req.body);
  const expected = crypto
    .createHmac('sha256', process.env.PAYLOCITY_WEBHOOK_SECRET)
    .update(payload)
    .digest('hex');


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


  const { eventType, data } = req.body;


  switch (eventType) {
    case 'employee.hired':
      await launchOnboardingWorkflow(data);
      break;
    case 'employee.terminated':
      await launchOffboardingWorkflow(data);
      break;
    case 'payroll.completed':
      await launchPayrollReviewWorkflow(data);
      break;
  }


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

Data mapping

Here’s how common Paylocity fields map to Tallyfy kick-off form fields. The Tallyfy column names the field you’re aiming at - in the API payload you address it by its timeline ID, not by this name.

Paylocity fieldTallyfy kick-off fieldDescription
employeeIdemployee_idUnique employee identifier
firstName + lastNamefull_nameEmployee full name
workEmailemailWork email address
departmentCodedepartmentDepartment code
costCentercost_centerCost center assignment
workLocationlocationWork location code
jobTitlejob_titleJob title
supervisorFirstNamemanagerDirect supervisor
employeeTypeemployee_typeFull-time, part-time, or contractor
hireDatestart_dateEmployee start date

Authentication

Paylocity uses OAuth 2.01 with the client credentials flow. Store credentials securely - don’t expose them in client-side code.

const getPaylocityToken = async () => {
  const response = await fetch(
    'https://api.paylocity.com/IdentityServer/connect/token',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/x-www-form-urlencoded'
      },
      body: new URLSearchParams({
        grant_type: 'client_credentials',
        client_id: process.env.PAYLOCITY_CLIENT_ID,
        client_secret: process.env.PAYLOCITY_CLIENT_SECRET,
        scope: 'WebLinkAPI'
      })
    }
  );


  return response.json();
};

iPaaS alternatives

If direct API work isn’t an option, consider these platforms:

  • Merge API - unified HRIS API with Paylocity support
  • Finch - employment system API with a Paylocity connector
  • Flexspring - HR integration platform
  • Workato - enterprise automation recipes

Vendors > Paylocity

Tallyfy picks up where Paylocity stops by coordinating the cross-department workflows that…

Footnotes

  1. Industry-standard protocol for secure third-party authorization without sharing passwords ↩

Get in touch
About Tallyfy