
Manage Deductions using EmployerLink
Use our APIs to manage payroll deductions.
This guide explains how to use EmployerLink to manage employee deductions with Atomic APIs. This assumes that you have previously enrolled an employer using Transact and have completed the initial sync of employees.
This guide will show you how to:
- Fetch Employees and their current deductions
- Create a new deduction
- Update deductions
- Delete deductions
- Check the status of a requested deduction change
Fetch Employees and their current deductions
Atomic regularly syncs with payroll providers and updates employees. (The frequency of this sync depends on your use case.)
First, retrieve your desired Employer ID using the Get Employers endpoint: /employers
employerId
you received in the employer-updated
webhook sent after the admin went through the Transact SDK to enroll the employer in question. To retrieve the employees, use the Get Employees
endpoint with the include
parameter set to employeeDeductions,identity
.
GET /employers/:employerId/employees?include=employeeDeductions,identity
You’ll receive a response like this:
{
"data": {
"nextCursor": "6387e1eba1dabf6708a16e39",
"previousCursor": "6387e1f194c2fdd82d90d404",
"employees": [
{
"_id": "employeeId",
"firstName": "John",
"lastName": "Doe",
"employer": "5f0361ec9ecb2400089f1451",
"employeeDeductions": [
{
"_id": "employeeDeductionId",
"createdAt": "2023-08-14T20:04:17.459Z",
"updatedAt": "2023-08-14T20:29:45.917Z",
"employee": "employeeId",
"startDate": "2022-02-02T00:00:00.000Z",
"endDate": "2023-02-02T00:00:00.000Z",
"label": "401k",
"amount": 10,
"calculation": "percent",
"category": "401k",
"categoryType": "pre-tax"
}
]
}
]
}
}
Of particular note are the _id
fields on the employeeDeduction
object. These will be used to make any changes to the deductions. In this document we will use the value employeeDeductionId
to correspond to this field. You will also need the _id
on the employee you wish to change, in this case the value employeeId
.
Use this data to determine what, if any, changes need to be made to the deductions in the payroll system.
From here, you can create, update, or delete deductions.
Create a new deduction
Deductions can be added in two ways: using an existing employerDeductionType
or by defining a employerDeductionType
in the createEmployeeDeduction
request.
We recommend the following steps to create deductions:
- Retrieve existing deduction types on an employer.
- Use the
label
on the existing deduction types to identify which deduction type you’d like to apply. - If the desired deduction type exists, apply the existing deduction to employees.
- If the desired type does not exist, or if the payroll provider does not support types, create a new deduction with the type defined inline.
Checking Deduction Types
Deduction types are unique for each employer you have enrolled. They represent previously applied deductions, and are used to consistently apply a deduction to multiple employees.
Not all payroll providers support deduction types. For example, Paychex requires their use and every deduction will have an employerDeductionType
, while Gusto only supports them in specific cases.
To see the employerDeductionType
available for an employer, use the endpoint:
GET /employers/:employerId/employer-deduction-types
This will return a response structured like this:
{
"data": {
"nextCursor": "6387e1eba1dabf6708a16e39",
"previousCursor": "6387e1f194c2fdd82d90d404",
"employerDeductionTypes": [
{
"_id": "employerDeductionTypeId",
"employer": "642c9aa6f8fc90e0dbb4c92f",
"amount": 10,
"calculation": "percent",
"category": "401k",
"categoryType": "pre-tax",
"endDate": "2023-02-02T00:00:00.000Z",
"label": "401k",
"startDate": "2022-02-02T00:00:00.000Z"
}
]
}
}
Identify the deduction you want to apply, and store the _id
field. This will be used to apply the deduction later.
If there are no employerDeductionTypes
, either because none have been created, or because the payroll provider does not support them, you will define the type when you create the employeeDeduction
.
trackingId
that we will use to link statuses and results to your original request. This is unique at the level of deduction request. Multiple employee deductions will share a trackingId
if they were applied together. You should store the trackingId
in such a way that you can reference it later. Creating an Employee Deduction
Creating an employeeDeduction
uses the same endpoint regardless of whether you are applying an existing employerDeductionType
or defining a new type.
Applying an Existing Deduction Type
If you were able to identify a deduction type, you can pass its _id
in the create request to apply it, as well as override the fields amount
or calculation
.
Make a POST
request to /employers/:employerId/employee-deductions
with a body structured like this.
{
"employeeDeductions": [
{
"_id": "employerDeductionTypeId",
"employees": [
{
"_id": "employeeId",
"amount": 100,
"calculation": "fixed",
"trackingId": "trackingId"
}
]
}
]
}
You can apply a deduction to multiple employees. You can also apply multiple different deductions in the same request. More detail available in the API reference here.
Creating without an existing Deduction Type
If you did not find a relevant employerDeductionType
, or if you want to create a new one, you can define the deduction in the request. Instead of sending an employeeDeductionId
, send a category
, categoryType
, label
, amount
, and calculation
. Take care to send a label
that will help you identify the deduction later, and that will also be meaningful to the employee as they may be able to see it.
{
"employeeDeductions": [
{
"category": "401k",
"categoryType": "pre-tax",
"label": "Retirement",
"amount": 100,
"calculation": "fixed",
"endDate": "2024-01-01T12:00:00.000Z",
"startDate": "2023-01-01T12:00:00.000Z",
"employees": [
{
"_id": "employeeId",
"amount": 10,
"calculation": "fixed",
"trackingId": "yourTrackingId"
},
{
"_id": "62d6e323e76f9f3380b8db77",
"amount": 20,
"calculation": "percent",
"trackingId": "yourTrackingId"
}
]
}
]
}
Update an Existing Deduction
Multiple fields can be changed on an employee’s deduction, including amount, calculation, start and end dates, etc.
In cases where modifying the deduction could result in unexpected results, we recommend creating a new deduction or deleting the deduction and creating a new one. (For example, changing from a pre to post tax deduction or changing the label)
To update the deduction, use the _id
field returned on the response from GET /employers/:employerId/employees?include=employeeDeductions
Send a request to PUT /employers/:employerId/employee-deductions
with the following body:
{
"employeeDeductions": [
{
"_id": "employeeDeductionId",
"amount": 100,
"calculation": "fixed",
"trackingId": "trackingId"
}
]
}
Any number of deductions can be included. For more information about the fields available, see the Update Existing Deductions reference.
Delete a Deduction
Deleting a deduction can be done in a similar manner to updating deductions.
Send a request to PUT /employers/:employerId/delete-employee-deductions
{
"employeeDeductions": [
{
"_id": "employeeDeductionId",
"trackingId": "trackingId"
}
]
}
This will remove the specified employeeDeductions.
trackingId
is an optional parameter, which is used for tracking deduction requests. Checking the status of your request
Atomic uses webhooks to report back the status of a request. Any deduction related task will send an employee-deductions-request
webhook. This will report back which requests succeeded or failed. It also includes data that can be used to filter our API to get more details.
The API can be accessed without the use of webhooks, but the webhook is preferred as it gives real-time status updates so you can action failures sooner.
The webhook has the following structure:
{
"eventType": "employee-deductions-request",
"eventTime": "2023-09-26T21:35:44.557Z",
"user": {
"_id": "602c4d53dc89c40008db562a",
"identifier": "YOUR_UNIQUE_IDENTIFIER"
},
"data": {
"uri": "https://api.atomicfi.com/employers/642c9aa6f8fc90e0dbb4c92f/employee-deduction-requests?taskId=6501f8249f904b6a29e6cc1c",
"employerId": "642c9aa6f8fc90e0dbb4c92f",
"employeeDeductionRequests": [
{
"state": "applied",
"trackingId": "0b6385c9-f1e4-4b3c-8881-3c8b124609e1",
"employee": "642df289af36e2ef5e1679dc",
"employerDeductionType": "64c3d74f9326b2e09de96089",
"task": "6501f8249f904b6a29e6cc1c",
"employeeDeduction": {
"_id": "6508ca7ebc39bd78ca1fb87d",
"label": "retirement",
"calculation": "fixed",
"category": "401k",
"categoryType": "post-tax",
"amount": 4,
"startDate": "2023-09-13T17:57:56.230Z"
}
},
{
"state": "failed",
"trackingId": "9681a900-d7a1-4fd2-a5da-0f1f3335dfcf",
"employee": "642df289af36e2ef5e1679d9",
"employerDeductionType": "64c3d74f9326b2e09de96089",
"task": "6501f8249f904b6a29e6cc1c",
"employeeDeduction": {
"_id": "6508ca8b882f46254b6934b7",
"label": "retirement",
"calculation": "percent",
"category": "other",
"categoryType": "pre-tax",
"amount": 20,
"startDate": "2023-09-13T17:57:56.230Z"
}
}
]
}
}
It provides an at-a-glance view of the state of a deduction request. Possible states are applied
, failed
, pending
, and updated
.
You can also use the endpoint GET /employee-deduction-requests
and use query parameters to filter trackingId
, employer
, employee
, etc. This will additionally include metadata, including the label
.
Please visit the webhooks page for additional details on all available EmployerLink webhooks.