Atomic logo
abstracted screenshot of successful enrollment in UI

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

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

You will need the 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:

GET Employees Response
{
  "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.

Deductions can be added in two ways: using an existing employerDeductionType or by defining a employerDeductionType in the createEmployeeDeduction request.

Note: Support for deduction types varies by payroll provider. When possible, we will save your deduction as a reusable type.

We recommend the following steps to create deductions:

  1. Retrieve existing deduction types on an employer.
  2. Use the label on the existing deduction types to identify which deduction type you’d like to apply.
  3. If the desired deduction type exists, apply the existing deduction to employees.
  4. 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.

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:

GET Deduction Types Response
{
  "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.

For all updates to state, you can send a 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 employeeDeduction uses the same endpoint regardless of whether you are applying an existing employerDeductionType or defining a new 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.

POST Employee Deductions Body
{
  "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.

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.

POST Employee Deductions Body
{
  "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"
        }
      ]
    }
  ]
}
Note: The default amounts and calculations for each deduction can be overridden by passing that data in the relevant employee objects in the request body.

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

Note: multiple deductions can be updated at once. For simplicity we only describe the steps to update one deduction.

Send a request to PUT /employers/:employerId/employee-deductions with the following body:

PUT Employer Deductions 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.

Deleting a deduction can be done in a similar manner to updating deductions.

Send a request to PUT /employers/:employerId/delete-employee-deductions

PUT Delete Deductions Body
{
  "employeeDeductions": [
    {
      "_id": "employeeDeductionId",
      "trackingId": "trackingId"
    }
  ]
}

This will remove the specified employeeDeductions.

Note: trackingId is an optional parameter, which is used for tracking deduction requests.

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:

Sample employee-deductions-request event
{
  "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.