Guide to payroll API integrations

Editor's note: This is a series on API-based integrations. Check out Merge if you're looking to add 40+ payroll integrations with one payroll API.

Getting paid: it’s more than important to you — it’s a BIG business to everyone else.

In the past few years, payroll tech has exploded. Concepts such as embedded payroll allow products to add payroll services without building it themselves. Novel consumer user cases, such as credit checks and lending software, are popping up to utilize the rich set of payroll data being made available. And with this growth, B2B software integrations are proliferating as the payroll system expands and innovates. 

So — how did this all happen? And how can you get up to date on this growing software trend to benefit your own business?

All of these changes are made possible by one critical piece of tech: payroll APIs that stitch together the entire payments ecosystem. 

This guide to Payroll APIs will teach you about:

• Top APIs - Which providers matter most
• Key concepts - How payroll works
• Data schemas - How various providers organize payroll data
• Use cases - Common ways payroll data is used in product integrations
• How to get started - Approaching payroll API integrations within your own product

Top payroll APIs

The team at Base 10 VC found more than 70 payroll-related companies that have received over $9B in investment. This includes heavyweight payroll providers raising hundreds of millions of dollars such as Rippling, Gusto, Zenefits, Namely, Payfit, Personio, Deel, Oyster, and DailyPay.

The payroll software market is very fragmented, with a few larger players that make up ~10% of revenue, and a long tail of other companies. If you’re building payroll integrations you’ll want to consider supporting the following payroll software providers.

{{this-blog-only-cta}}

Key payroll API concepts for developers

Understanding payroll APIs begins with understanding payroll. And if you’re unfamiliar with the space, then heads up: it might seem a bit complicated at first. To help you, here are the key concepts you need to know to start interacting with payroll data today.

Companies and employees

The fundamental context for all payroll API interactions are companies and the employees (or contractors) that work there. This forms the basis of how you’ll typically query for data will provide attributes about the employee valuable for additional context (e.g. location).

Pay periods, payroll runs, and statuses

Payroll systems are built around the core concept of a ‘Pay Period’ (e.g., monthly, twice monthly) and ‘Payroll Runs’ that occur once every period. Within ‘Payroll Runs’, there are both ‘Regular’ runs as well as one-time ‘Off-Cycle’ runs that can occur to fix a mistake or pay someone immediately upon termination. Each ‘Payroll Run’ has a status that it goes through, from ‘unprocessed’ through to ‘paid.’ You’ll almost always be interacting with data specific to a payroll run with a defined pay period (e.g. deductions related to the last completed payroll run).

Jobs and pay rates

Chances are one of the key attributes you want to know about an employee is how much they earn. Figuring out how much someone earns involves finding their ‘Job’, typically defined as a specific ‘Title’, as well as a ‘Pay Rate’. Each ‘Job’ has either an associated ‘Pay Rate’ or ‘Compensations’. Both can include the cash compensation per unit of time (e.g., $ per hour) and may also include other compensation, such as commissions, bonuses, or one-time payments. 

Tip: In many payroll and HR systems a ‘Job’ is unique to a specific employee: one employee may have two ‘Jobs’ but two employees won’t have the same ‘Job’.

Employee pay 

A ‘Pay Rate’ is just the beginning of calculating what an employee will actually receive in their bank account. The ‘Pay Rate’ times the time period worked (e.g. 80 hours over 2 weeks) will generate a ‘Gross Pay’ amount. From that, there are ‘Pre-Tax Deductions’, ‘Tax’, ‘Post-Tax Deductions’, and ‘Reimbursements’. 

Tip: In a Payroll API such as Merge, you’ll typically find these within the Earnings, Deductions, and Taxes objects.

Employer cost 

Payments also occur on the employer side. In addition to the ‘Employee Gross’ pay (based on the concepts described above), there is ‘Employer Tax’ (e.g. payroll taxes, social insurance taxes), and ‘Contribution to Benefits’ that employers make on behalf of their employees. 

Tip: In a payroll API, you’ll find these under the Benefits object.

{{this-blog-only-cta}}

Payroll API data schemas

Each Payroll API has a schema specific to that platform. A typical data schema looks like the one below, modeled off of Merge’s Payroll Unified API.

Employees typically include all full-time workers, part-time workers, and contractors. Demographic information (birthdates, government IDs) and addresses are available from the employee object. Addresses are often stored as an array of ‘Locations’ objects. Employees are associated with their Bank Info for direct deposit.

Each employee has one or many Employments that define their current roles and compensation. This includes job title, pay rate and frequency, and the Pay Groups they belong to.

Employees are also associated with Benefits that they enroll in. The Benefit object includes information about how much the employee and the employer contribute each pay period.

To determine how much someone was paid or will be paid, it’s important to use the Employee Payroll Runs object. For each employee, you’ll be able to access the gross pay, net pay, earnings, deductions, and taxes for each pay period. This is also the object you’ll want to use to post new line items to the payroll. You can find the appropriate run by using the Payroll Runs object and filtering on the date or run type.

Each Employee Payroll Run has Deductions paid by either the employee or the company. These deductions represent one-time debits for a specific employee. While some Payroll APIs support the concepts of recurring deductions or company-wide deductions, these concepts aren’t common among most APIs. Note that for most Payroll APIs, benefits such as health insurance may or may not be mapped to deductions.

Relevant HRIS API data schemas

In addition to core payroll information, you’ll also find related HR information to be valuable in your product integration. These objects include Teams, which define employees in hierarchical or local groups. You may also want to access information about Time Off to map back to the payroll line items of a given employee. 

Top payroll API use cases

Payroll data is used in a wide variety of B2B and B2C products. Here are the most common examples of payroll data integrations.

Employee onboarding

When full-time or part-time users are onboarded to a new company they need to set up payroll, bank account, tax status, and deduction information so that they can get paid.

Examples: Sapling, Zavvy

See: The Sapling pre-onboarding flow sends new hire payroll and tax data to ADP.

Employee reimbursements

Workers spend money out-of-pocket (travel, mileage, per-diems) that they want to be reimbursed by their employer. Payroll data can provide bank account information and tax tracking necessary to make reimbursements seamless.

Examples: Ramp, Brex, Navan, Mesh Payments, Airbase, Expensify

Benefit administration and deductions

Employers offer health, mental health, insurance, fitness, referral bonuses, transport, and other fringe benefits. Payroll data makes it easy to deduct from employee paychecks, company accounts, and to keep track of taxes.

Examples: Forma, Origin, Paytient, Benepass, Bonusly, Assembly

Global employment and tax management

Hiring and managing teams in multiple countries lead to increased payroll complexity. Integrating with payroll data allows you to create streamlined compliance workflows by using data such as employee address, earnings, and tax payment info.

Examples: Remote, Oyster, Deel

Compensation management

Employers need to ensure salary and equity pay are competitive and equitable. Payroll and HR data makes it easy to view and compare compensation across locations, titles/roles, and demographic data.

Examples: Pave, Pequity, Assemble, Carta Total Comp, Barley, Complete, Compete

See: Carta’s Total Compensation integration with Gusto for leveling and benchmarking.

Accounting, financial planning, and analytics

Employers want to reduce manual labor by syncing payroll to accounting systems and performing financial analysis by teams or departments. Payroll data integrations make it possible to read data from and write data to financial systems.

Example: Mosaic, Causal, Jirav, Quickbooks

See: Quickbooks integration in Gusto mapping payroll line items with general ledger accounts.

Time management

Employers use time tracking software to calculate payroll, sometimes as part of their payroll system and sometimes from external products. Integrating time management and payroll systems makes it easy to sync hours worked, tips accrued, and payroll paid.

Examples: Factorial, Deputy, Homebase, QuickBooks Time, When I Work

See: Homebase integrates with ADP to export timecards for payroll processing.

Consumer banking and lending

Consumers can benefit from increased access to banking, lending, and credit products by connecting accounts to their work payroll provider. Payroll data enables income verification, employment verification, and garnishment for debt collection.

Examples: DailyPay, Branch

See: DailyPay payroll advance powered by integration with ADP.

Getting started with payroll APIs

Once you’re ready to kick the tires on integrating with a payroll provider, you’ll want to keep in mind a few additional topics:

• API format - REST, SOAP, etc.
• Authentication
• Pagination
• Rate Limits 
• Test Accounts

We’ve built Merge to help make integrating with multiple payroll providers as easy as possible. Our HR, Payroll, and Directory Unified API is REST-based, and uses a standard approach to authentication, pagination, and rate limiting to make your development simple. Hundreds of companies use Merge to plug into payroll APIs, including the team at Ramp for compensation management.

If you're curious about learning more, reach out to our team for a demo, or sign up and get API access for free, today.!