Skip to content
Tallyfy

Paylocity technical integration

Integration options

Section titled “Integration options”

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

REST API integration

Section titled “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.

Each prerun value’s shape depends on the field type. The per-type list lives on Launch process.

Webhook integration

Section titled “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

Section titled “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

Section titled “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

Section titled “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
Section titled “Related articles”

Vendors > Paylocity

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

Footnotes

Section titled “Footnotes”

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

Get in touch
About Tallyfy