Manage Deductions using EmployerLink

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

To retrieve the employees, use the Get Employees endpoint with the include parameter set to 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:

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.

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:

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.

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.

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.