EmployerLink API Reference

Atomic's API is built around RESTful principles, using JSON encoded request and response bodies.

To get going quickly, we recommend using Postman - an API collaboration tool. Atomic provides a public workspace which you can fork into your own workspace. Use the button below to get started.

The workspace comes fully documented with:

several useful flows using our APIs
requests for all of the Atomic endpoints
an environment containing placeholders for all the variables needed to connect to your Sandbox instance of Console

Authentication

Atomic uses a combination of API keys and access tokens to authenticate requests. Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, etc.

API Key and Secret

You can retrieve and manage your API key and secrets on the credentials page on the Atomic Console. Include these headers in requests that are secured with your API Key and Secret:

Header	Description
`x-api-key`	API Key for your Atomic account
`x-api-secret`	API Secret for your Atomic account

Access Token

These headers are included in requests that are made by the end user, e.g. searching for their employer.

Header	Description
`x-public-token`	Public token generated during access token creation.

Errors

Our API returns standard HTTP success or error status codes. For errors, we will also include extra information about what went wrong encoded in the response as JSON. The various HTTP status codes we might return are listed below.

Code	Title	Description
200	OK	The request was successful.
400	Bad Request	The request was unacceptable.
401	Unauthorized	Missing or invalid credentials.
404	Not Found	The resource does not exist.
422	Validation error	A validation error occurred.
50X	Internal Server Error	An error occurred with our API.

API Versioning

The Atomic API accepts an x-atomic-version header. This is a mechanism we have put in place to ensure stability as the surface of the API changes over time. A new version will be released when there are backward incompatible changes to the API. We will publish a changelog and migration guides as new versions are rolled out to highlight any relevant changes and make migrations seamless for consumers of our API.

To use the version header, append the x-atomic-version header to all calls to the Atomic API. The value of the header will follow standardized CalVer practices. The current version is 2022-12-02.

x-atomic-versionDate: A Date-string in the form of YYYY-MM-DD. Specific versions to be provided by Atomic.

Header	Description
`x-atomic-version`	Date string of the required API version

Access Token

An AccessToken grants access to Atomic's API resources for an end user when its value is used as the x-public-token header.

Create Access Token

Authentication is handled via the API Key and Secret method. This API is intended to be called from your backend service so your API Keys and Secrets are not deployed to your client side application.

Required Properties

identifierstring: A unique identifier from your system that will be used to reference this user. This could be a primary key used in your system or another unique identifier. Creating multiple access tokens with the same identifier will tie those tokens to the same user in Atomic's system.

Optional Properties

tokenLifetimeinteger

The number of seconds until the token expires.

Default value: 86,400 (24 hours)

Products may have additional required properties. Refer to the implementation pages for additional details.

POST/access-token

https://sandbox-api.atomicfi.com/access-token

Product Specific Properties

The identifier property is required for generating all AccessTokens, but each Atomic product may require some additional context in order to correctly set up the flow in our backend. Please refer to the implementation pages for each Product to get specific details regarding AccessToken creation.

Deposit

Verify

Response

Successfully creating an Access Token will return a payload with a data object containing a publicToken. The publicToken may be used to initialize the Transact SDK and is valid for tokenLifetime seconds.

Example response

{
  "data": {
    "publicToken": "6e93549e-3571-4f57-b0f7-77b7cb0b5e48"
  }
}

Employees

Get Employees

Authentication is handled via the API Key and Secret method. This API is intended to be called from your backend service so your API Keys and Secrets are not deployed to your client side application.

Required Properties

_idstring: The _id of the employer that the employees belong to.

Optional Properties

nextCursorstring

The cursor to use to retrieve the next page of data.

previousCursorstring

The cursor to use to retrieve the previous page of data

limitinteger

The max number of employees to return.

includestring

A comma separated list of employment data objects to include. Each list item will be one of the following: employeeDeductions, depositAccounts, employment, identity, income, statements, timesheets, ortaxes. If this parameter is present, only the corresponding data objects will be returned. If this parameter is missing, only _id, firstName, lastName, and employer will be returned.

GET/employers/:_id/employees

https://sandbox-api.atomicfi.com/employers/:_id/employees

Response

A successful request will return a paginated list of employees in ascending order of creation.

nextCursorstring: The cursor to use to get the next page of data. If null, the end of the data has been reached.
previousCursorstring: The cursor to use to get the previous page of data. If null, there is no previous page of data.
employees[]: An array of objects representing an employee. Each object will contain _id, firstName, lastName, andemployer fields, as well any additional fields requested by the includeparameter.

Example response

{
  "data": {
    "nextCursor": "6387dd18118deb05b68f0bde",
    "previousCursor": "6387dd0f1a5c71c793b4b507",
    "employees": [
      {
        "_id": "5eea73d5f55d6c0007d1fcdf",
        "firstName": "John",
        "lastName": "Doe",
        "employer": "5f03900c13857400082e9497"
      },
      {
        "_id": "5eea76350d0ada0007fb43c7",
        "firstName": "Jane",
        "lastName": "Doe",
        "employer": "5f03900c13857400082e9497"
      }
    ]
  }
}

Get an Employee

Authentication is handled via the API Key and Secret method. This API is intended to be called from your backend service so your API Keys and Secrets are not deployed to your client side application.

Required Properties

_idstring: The _id of the employee.

Optional Properties

includestring

A comma separated list of employment data objects to include. Each list item will be one of the following: deductions, depositAccounts, employeeDeductions, employment, identity, income, statements, timesheets, ortaxes. If this parameter is present, only the corresponding data objects will be returned. If this parameter is missing, all fields are returned.

GET/employees/:_id

https://sandbox-api.atomicfi.com/employees/:_id

Response

A successful request will return an employee.

dataobject: An object containing employment data for a given employee. This data will be a union of the following objects: depositAccounts, employment, identity, income, statements, and taxes. Timestamps for createdAt and updatedAt are also included.

Example response

{
  "data": {
    "_id": "5eea73d5f55d6c0007d1fcdf",
    "depositAccounts": [
      {
        "routingNumber": "123123123",
        "accountNumber": "1122330000",
        "type": "checking",
        "bankName": "Molecular Bank",
        "distributionType": "percent",
        "distributionAmount": 80
      },
      {
        "routingNumber": "456456456",
        "accountNumber": "XXXX1111",
        "type": "savings",
        "bankName": "Molecular Bank",
        "distributionType": "percent",
        "distributionAmount": 20
      }
    ],
    "employeeType": "fulltime",
    "employmentStatus": "active",
    "jobTitle": "Product Manager",
    "startDate": "2017-04-19T12:00:00.000Z",
    "weeklyHours": 40,
    "classCode": 8810,
    "terminationDate": "2019-09-01T12:00:00.000Z",
    "firstName": "Jane",
    "lastName": "Appleseed",
    "dateOfBirth": "1984-04-12T12:00:00.000Z",
    "email": "janeappleseed@example.com",
    "phone": "5558881111",
    "ssn": "111223333",
    "homeAddress": {
      "line1": "123 Example St.",
      "line2": "Apt. 345",
      "city": "Salt Lake City",
      "state": "UT",
      "zipcode": "84111",
      "country": "USA"
    },
    "income": 45000,
    "incomeType": "yearly",
    "payCycle": "weekly",
    "statements": [
      {
        "_id": "642c9aa7f8fc90e0dbb4ca71",
        "createdAt": "2023-04-04T21:46:15.762Z",
        "updatedAt": "2023-08-14T20:29:45.419Z",
        "employee": "64b820a19cba026a0245feeb",
        "date": "2020-06-15T12:00:00.000Z",
        "payPeriodStartDate": "2020-05-27T12:00:00.000Z",
        "payPeriodEndDate": "2020-06-12T12:00:00.000Z",
        "grossAmount": 1000,
        "ytdGrossAmount": 10000,
        "netAmount": 800,
        "ytdNetAmount": 8000,
        "paymentMethod": "deposit",
        "hours": 39,
        "deductions": [
          {
            "category": "taxes",
            "label": "Federal Income Tax",
            "rawLabel": "Federal Income Tax",
            "amount": 200,
            "ytdAmount": 2000
          },
          {
            "category": "taxes",
            "label": "State Income Tax",
            "rawLabel": "Utah State Tax",
            "amount": 50,
            "ytdAmount": 500
          },
          {
            "category": "other",
            "label": "Abc corp dd",
            "rawLabel": "Abc corp dd",
            "amount": 5,
            "ytdAmount": 50
          }
        ],
        "earnings": [
          {
            "category": "benefit",
            "rawLabel": "Social Security (Disability)",
            "amount": 1000
          },
          {
            "category": "bonus",
            "rawLabel": "Quarterly Bonus",
            "amount": 2000,
            "ytdAmount": 6000
          },
          {
            "category": "overtime",
            "rawLabel": "Overtime Pay",
            "amount": 100,
            "ytdAmount": 1000,
            "hours": 10,
            "rate": 15
          },
          {
            "category": "reimbursement",
            "rawLabel": "Gas Card",
            "amount": 25.47,
            "ytdAmount": 85.74
          }
        ],
        "netAmountAdjustments": [
          {
            "label": "Mileage Reimbursement",
            "amount": 25
          }
        ]
      },
      {
        "_id": "64b820a19cba026a0245feed",
        "createdAt": "2023-08-07T22:01:28.305Z",
        "updatedAt": "2023-08-14T20:29:45.419Z",
        "employee": "64b820a19cba026a0245feeb",
        "date": "2020-06-30T12:00:00.000Z",
        "payPeriodStartDate": "2020-05-27T12:00:00.000Z",
        "payPeriodEndDate": "2020-06-12T12:00:00.000Z",
        "grossAmount": 1000,
        "paymentMethod": "check",
        "hours": 37,
        "deductions": [
          {
            "category": "taxes",
            "label": "Federal Income Tax",
            "rawLabel": "Federal Income Tax",
            "amount": 200
          },
          {
            "category": "taxes",
            "label": "State Income Tax",
            "rawLabel": "Utah State Tax",
            "amount": 50
          },
          {
            "category": "other",
            "label": "Abc corp dd",
            "rawLabel": "Abc corp dd",
            "amount": 5
          }
        ]
      }
    ],
    "taxes": [
      {
        "type": "w2",
        "year": "2020-01-01T00:00:00.000Z",
        "totalWages": 50000
      },
      {
        "type": "w2",
        "year": "2021-01-01T00:00:00.000Z",
        "totalWages": 55000
      }
    ],
    "createdAt": "2023-02-28T19:57:26.445Z",
    "updatedAt": "2023-02-28T21:18:55.490Z"
  }
}

Employee Deduction Requests

An Employee Deduction Request is when a deduction is submitted to Atomic in order to write the deduction to the payroll system. This endpoint gives you a way to get the status of those requests and has several ways for you to filter them down to get to the data you need.

An Employee Deduction Request can be in any of these states: `processing`, `applied`, or `failed`.

Get Employee Deduction Request

Authentication is handled via the API Key and Secret method. This API is intended to be called from your backend service so your API Keys and Secrets are not deployed to your client side application.

Required Properties

_idstring: The _id of the employer that the deduction request belong to.

Optional Properties

employeeIdstring

The employee identifier used which can be used to filter the employee deduction requests to ones made for a specific employee.

statestring

The state used to filter the employee deduction requests. This is an enum which can be one of the following: processing, applied, or failed.

trackingIdstring

The trackingId is an optional identifier you can pass in when creating the deduction specifically for tracking purposes.

taskIdstring

The task identifier used to filter the employee deduction requests. This will have been sent to your system in the webhook associated with the deduction request.

nextCursorstring

The cursor to use to retrieve the next page of data.

previousCursorstring

The cursor to use to retrieve the previous page of data

limitinteger

The max number of employee deduction requests to return.

GET/employers/:_id/employee-deduction-requests

https://sandbox-api.atomicfi.com/employers/:_id/employee-deduction-requests

Response

A successful request will return a paginated list of employee deduction requests in ascending order of creation.

employeeDeductionRequests[EmployeeDeductionRequest]: An array of objects representing an Employee Deduction Request. Each object will contain _id, trackingId, customer, employee, employer, employerDeductionType, state, task, andemployeeDeduction fields.
nextCursorstring: The cursor to use to get the next page of data. If null, the end of the data has been reached.
previousCursorstring: The cursor to use to get the previous page of data. If null, there is no previous page of data.

Example response

{
  "data": {
    "nextCursor": "6387dd18118deb05b68f0bde",
    "previousCursor": "6387dd0f1a5c71c793b4b507",
    "employeeDeductionRequests": [
      {
        "_id": "64af13c7e919bd3efbed494e",
        "trackingId": "a1f23a50-e36e-409b-8c05-a55ed4cd8d63",
        "customer": "5e978dcf3abbf90008a00b7a",
        "employee": "642df289af36e2ef5e1679dc",
        "employer": "64949a939e688f909acd70e6",
        "employerDeductionType": "6439618cfc32f24ab9933047",
        "state": "applied",
        "task": "65022b04c88cf9b8aaa0147e",
        "employeeDeduction": {
          "_id": "6508ca7ebc39bd78ca1fb87d",
          "label": "retirement",
          "calculation": "fixed",
          "category": "401k",
          "categoryType": "post-tax",
          "amount": 4,
          "startDate": "2023-09-13T17:57:56.230Z"
        }
      },
      {
        "_id": "64af19aa4bff9f438210a6e1",
        "trackingId": "3a4c0f51-0330-49f7-94d6-fc1499b5d1a7",
        "customer": "5e978dcf3abbf90008a00b7a",
        "employee": "642df289af36e2ef5e1679d9",
        "employer": "64949a939e688f909acd70e6",
        "employerDeductionType": "6439618cfc32f24ab9933047",
        "state": "failed",
        "task": "65022b0ce9d34a15e4a31c9e",
        "employeeDeduction": {
          "_id": "6508ca8b882f46254b6934b7",
          "label": "retirement",
          "calculation": "percent",
          "category": "other",
          "categoryType": "pre-tax",
          "amount": 20,
          "startDate": "2023-09-13T17:57:56.230Z"
        }
      }
    ]
  }
}

Employers

Get Employers

Authentication is handled via the API Key and Secret method. This API is intended to be called from your backend service so your API Keys and Secrets are not deployed to your client side application.

Optional Properties

userIdentifierstring

Filter the employers sent back in the response by optionally passing the identifier used to launch Transact when the HR admin connected their payroll provider.

nextCursorstring

The cursor to use to retrieve the next page of data.

previousCursorstring

The cursor to use to retrieve the previous page of data

limitinteger

The max number of employees to return.

GET/employers

https://sandbox-api.atomicfi.com/employers

Response

A successful request will return a paginated list of employers in ascending order of creation.

nextCursorstring: The cursor to use to get the next page of data. If null, the end of the data has been reached.
previousCursorstring: The cursor to use to get the previous page of data. If null, there is no previous page of data.
employers[Employer]: An array of objects representing an employer. Each object will contain _id and name.

Example response

{
  "data": {
    "nextCursor": "6387e1eba1dabf6708a16e39",
    "previousCursor": "6387e1f194c2fdd82d90d404",
    "employers": [
      {
        "_id": "5eea73d5f55d6c0007d1fcdf",
        "name": "Example Employer A"
      },
      {
        "_id": "5eea76350d0ada0007fb43c7",
        "name": "Example Employer B"
      }
    ]
  }
}

Get an Employer

Authentication is handled via the API Key and Secret method. This API is intended to be called from your backend service so your API Keys and Secrets are not deployed to your client side application.

Required Properties

_idstring: The _id of the employer.

GET/employers/:_id

https://sandbox-api.atomicfi.com/employers/:_id

Response

A successful request will return an employer.

_idstring: The _id of the employer.
namestring: The employer's name.
einstring: The employer's Employer Identification Number.
connectorobject: The payroll provider used by the referenced employer. Atomic refers to these as connector's in our system.
Child Properties
Optional Properties
_idstring
A unique identifier for the payroll provider in the Atomic system.
namestring
A human-readable name for the payroll provider.
locations[object]: A list of locations for the employer
Child Properties
Optional Properties
line1string
First line of the address of the employer.
line2string
Second line of the address of the employer.
citystring
City where the employer is located.
statestring
State where the employer is located.
postalCodestring
Postal code for the employer.
countrystring
Country where the employer is located.
createdAtdate: The date the employer data was initially retrieved.
updatedAtdate: The date the employer data was most recently retrieved.

Example response

{
  "data": {
    "_id": "5eea76350d0ada0007fb43c7",
    "name": "Example Employer A",
    "ein": "12345678",
    "connector": {
      "_id": "dd5376350d0ada0007f2f5sh",
      "name": "Payroll System A"
    },
    "locations": [
      {
        "line1": "12345 Enterprise Rd",
        "line2": "Suite 105",
        "city": "Salt Lake City",
        "state": "UT",
        "postalCode": "84111",
        "country": "USA"
      }
    ],
    "createdAt": "2023-02-28T19:57:26.445Z",
    "updatedAt": "2023-02-28T21:18:55.490Z"
  }
}

Employer Documents

Frequently, additional documentation is required for various use cases. This endpoint will be used to retrieve said documents from the Atomic system as we are able to pull them from the HR systems.

Get Employer Documents

This endpoint returns a paginated list of Employer Documents reference data. Each object contains an _id which can be used to get the document from the Atomic system.

Authentication is handled via the API Key and Secret method. This API is intended to be called from your backend service so your API Keys and Secrets are not deployed to your client side application.

Required Properties

_idstring: The _id of the employer that the employer documents belong to.

Optional Properties

nextCursorstring

The cursor to use to retrieve the next page of data.

previousCursorstring

The cursor to use to retrieve the previous page of data

limitinteger

The max number of employees to return.

GET/employers/:_id/employer-documents

https://sandbox-api.atomicfi.com/employers/:_id/employer-documents

Response

A successful request will return a paginated list of employer documents in ascending order of creation.

nextCursorstring: The cursor to use to get the next page of data. If null, the end of the data has been reached.
previousCursorstring: The cursor to use to get the previous page of data. If null, there is no previous page of data.
employerDocuments[EmployerDocument]: An array of objects representing an employer document. Each object will contain _id, employer, type, date, and metadata.

Example response

{
  "data": {
    "nextCursor": "6387e1eba1dabf6708a16e39",
    "previousCursor": "6387e1f194c2fdd82d90d404",
    "employerDocuments": [
      {
        "_id": "63fe5ca6d93310ec79aee4f1",
        "employer": "63f7f2e7baf8f344eacd59fd",
        "type": "941",
        "date": "2021-01-01T00:00:00.000Z",
        "metadata": {
          "startDate": "2021-01-01T00:00:00.000Z",
          "endDate": "2021-03-01T00:00:00.000Z"
        }
      },
      {
        "_id": "63fe5ca6d93310ec79aee4f2",
        "employer": "63f7f2e7baf8f344eacd59fd",
        "type": "941",
        "date": "2021-03-01T00:00:00.000Z",
        "metadata": {
          "startDate": "2021-03-01T00:00:00.000Z",
          "endDate": "2021-06-01T00:00:00.000Z"
        }
      }
    ]
  }
}

Get an Employer Document

Use this endpoint to retrieve Employer Documents from the Atomic system using the _id received from calls to /employer-documents

Authentication is handled via the API Key and Secret method. This API is intended to be called from your backend service so your API Keys and Secrets are not deployed to your client side application.

Required Properties

_idstring: The _id of the employer document.

GET/employer-documents/:_id

https://sandbox-api.atomicfi.com/employer-documents/:_id

Response

A successful request will return data about an employer document including url, which is a generated link to download the document from the Atomic system.

_idstring: The _id of the employer document.
typestring: The type of the employer document. For example "941" would be a Form 941.
datedate: A timestamp of when the document was filed, stored in UTC and ISO 8601 format.
metadataobject: Additional metadata about the document.
urlstring: The URL to download the form. Each request to this endpoint will generate a new URL, which will expire after 1 hour.
createdAtdate: The date the document was initially retrieved.
updatedAtdate: The date the document was most recently retrieved.

Example response

{
  "data": {
    "_id": "63fe5ca6d93310ec79aee4f1",
    "employer": "63f7f2e7baf8f344eacd59fd",
    "type": "941",
    "date": "2021-01-01T00:00:00.000Z",
    "metadata": {
      "startDate": "2021-01-01T00:00:00.000Z",
      "endDate": "2021-03-01T00:00:00.000Z"
    },
    "url": "[ATOMIC-GENERATED-PRESIGNED-S3-URL]",
    "createdAt": "2023-02-28T19:57:26.445Z",
    "updatedAt": "2023-02-28T21:18:55.490Z"
  }
}

Employer Deduction Types

Many payroll systems have the ability to create templates for deductions so they can be used multiple times. These endpoints will retrieve templates that are available in the payroll system. Using the _id, you will be able to get more information about a specific deduction type or apply the deduction type to write a deduction for an employee or list of employees.

Get Employer Deduction Types

Get all Deduction Types for an Employer.

Authentication is handled via the API Key and Secret method. This API is intended to be called from your backend service so your API Keys and Secrets are not deployed to your client side application.

Required Properties

_idstring: The _id of the employer that the deduction types belong to.

Optional Properties

nextCursorstring

The cursor to use to retrieve the next page of data.

previousCursorstring

The cursor to use to retrieve the previous page of data

limitinteger

The max number of employees to return.

GET/employers/:_id/employer-deduction-types

https://sandbox-api.atomicfi.com/employers/:_id/employer-deduction-types

Response

A successful request will return a paginated list of employer deduction types in ascending order of creation.

nextCursorstring: The cursor to use to get the next page of data. If null, the end of the data has been reached.
previousCursorstring: The cursor to use to get the previous page of data. If null, there is no previous page of data.
employerDeductionTypes[EmployerDeductionType]: An array of objects representing an employer deduction type. Each object will contain _id, employer, amount, calculation, label, category, categoryType, startDate, and endDate.

Example response

{
  "data": {
    "nextCursor": "6387e1eba1dabf6708a16e39",
    "previousCursor": "6387e1f194c2fdd82d90d404",
    "employerDeductionTypes": [
      {
        "_id": "642703b666b8c0abb8c65cff",
        "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"
      },
      {
        "_id": "642703b666b8c0abb8c65d01",
        "employer": "642c9aa6f8fc90e0dbb4c92f",
        "amount": 100,
        "calculation": "fixed",
        "category": "Other",
        "label": "Life Insurance"
      },
      {
        "_id": "642703b666b8c0abb8c65d03",
        "employer": "642c9aa6f8fc90e0dbb4c92f",
        "label": "Garnishment",
        "category": "Garnishment"
      }
    ]
  }
}

Get an Employer Deduction Type

Get a specific Deduction Type for an Employer.

Authentication is handled via the API Key and Secret method. This API is intended to be called from your backend service so your API Keys and Secrets are not deployed to your client side application.

Required Properties

_idstring: The _id of the employer deduction type.

GET/employer-deduction-types/:_id

https://sandbox-api.atomicfi.com/employer-deduction-types/:_id

Response

A successful request will return an employer deduction type.

_idstring: The _id of the employer deduction type.
amountnumber: The amount of the deduction type in dollars if calculation is fixed or percentage if calculation is percent.
calculationstring: Either fixed or percent.
categorystring: One of 401k, 401k-catchup, 403b, 408b, 408k, premium-only-plan, garnishment, or other
categoryTypestring: Either pre-tax or post-tax.
createdAtdate: The date the employer deduction type was initially retrieved.
employerstring: The _id of the employer.
endDatedate: The date at which the applied deduction will expire in the payroll system.
labelstring: The label of the employer deduction type.
startDatedate: The date at which the applied deduction type began in the payroll system
updatedAtdate: The date the employer deduction data was most recently retrieved from the payroll system.

Example response

{
  "data": {
    "_id": "642703b666b8c0abb8c65cff",
    "amount": 10,
    "calculation": "percent",
    "category": "401k",
    "categoryType": "pre-tax",
    "createdAt": "2023-03-31T16:00:54.321Z",
    "employer": "642c9aa6f8fc90e0dbb4c92f",
    "endDate": "2023-02-02T00:00:00.000Z",
    "label": "401k",
    "startDate": "2022-02-02T00:00:00.000Z",
    "updatedAt": "2023-04-04T21:46:16.694Z"
  }
}

Deductions

Deductions can be added to any number of employees either by referencing an existing employer deduction type on file in the payroll system or by specifying a new deduction type to be created and applied to the referenced employees.

These methods can be used in combination to apply existing and newly created deductions to employees, if so desired. The endpoint is the same, but the request body will differ depending on the use case.

Apply Existing Deductions

Using an _id from the Employer Deduction Types endpoint, you can reference an existing deduction type to apply it to a list of employees for a given employer.

Authentication is handled via the API Key and Secret method. This API is intended to be called from your backend service so your API Keys and Secrets are not deployed to your client side application.

Required Properties

employeeDeductions[Deduction Type]

The list of deductions to apply to the referenced employees. This example references deduction types on file in the payroll system.

Child Properties

Required Properties

employerDeductionTypeIdstring

The _id of the employer deduction type to be applied.

employees[Employee]

Child Properties

Required Properties

_idstring: The _id of the employee.

Optional Properties

amountnumber

The amount of the deduction type in dollars if calculation is fixed or percentage if calculation is percent.

calculationstring

Either fixed or percent.

trackingIdstring

A unique string that we store alongside your request, used to query the status of the deduction.

POST/employers/:_id/employee-deductions

https://sandbox-api.atomicfi.com/employers/:_id/employee-deductions

Response

A successful request will return the _id's of the associated Task and Task Workflow, which is a grouping of any Tasks needed to complete the request to the payroll system.

taskWorkflow._idstring: The _id of the Task Workflow.
taskWorkflow.tasks[0]._idstring: the _id of the Task.

Example response

{
  "data": {
    "taskWorkflow": {
      "_id": "6387e1eba1dabf6708a16e39",
      "tasks": [
        {
          "_id": "5eea76350d0ada0007fb43c7"
        }
      ]
    }
  }
}

Create a New Deduction

Create new deductions on demand and apply them to a list employees.

Authentication is handled via the API Key and Secret method. This API is intended to be called from your backend service so your API Keys and Secrets are not deployed to your client side application.

Required Properties

employeeDeductions[Deduction Type]

The list of deductions to apply to the referenced employees. This example creates a new deduction type on demand and then applies it to the list of employees.

Child Properties

Required Properties

categorystring

One of 401k, 401k-catchup, 403b, 408b, 408k, premium-only-plan, garnishment, or other

categoryTypestring

Either pre-tax or post-tax.

labelstring

The label of the employer deduction type.

employees[Employee]

The employees to apply the deductions to.

Child Properties

Required Properties

_idstring: The _id of the employee.

Optional Properties

amountnumber

The amount of the deduction type in dollars if calculation is fixed or percentage if calculation is percent.

calculationstring

Either fixed or percent.

trackingIdstring

A unique string that we store alongside your request, used to query the status of the deduction.

Optional Properties

amountnumber

The amount of the deduction type in dollars if calculation is fixed or percentage if calculation is percent.

calculationstring

Either fixed or percent.

endDatedate

The date at which the applied deduction will expire in the payroll system.

startDatedate

The date at which the applied deduction type began in the payroll system

POST/employers/:_id/employee-deductions

https://sandbox-api.atomicfi.com/employers/:_id/employee-deductions

Response

A successful request will return the _id's of the associated Task and Task Workflow, which is a grouping of any Tasks needed to complete the request to the payroll system.

taskWorkflow._idstring: The _id of the Task Workflow.
taskWorkflow.tasks[0]._idstring: the _id of the Task.

Example response

{
  "data": {
    "taskWorkflow": {
      "_id": "6387e1eba1dabf6708a16e39",
      "tasks": [
        {
          "_id": "5eea76350d0ada0007fb43c7"
        }
      ]
    }
  }
}

Update Existing Deductions

Update deductions that have been perviously applied.

Authentication is handled via the API Key and Secret method. This API is intended to be called from your backend service so your API Keys and Secrets are not deployed to your client side application.

Required Properties

employeeDeductions[Deduction Type]

The list of employee deductions to update.

Child Properties

Required Properties

_idstring: The _id of the existing employee deduction.

Optional Properties

amountnumber

The amount of the deduction type in dollars if calculation is fixed or percentage if calculation is percent.

calculationstring

Either fixed or percent.

startDatedate

The date at which the applied deduction type began in the payroll system

endDatedate

The date at which the applied deduction will expire in the payroll system.

trackingIdstring

A unique string that we store alongside your request, used to query the status of the deduction.

PUT/employers/:_id/employee-deductions

https://sandbox-api.atomicfi.com/employers/:_id/employee-deductions

Response

A successful request will return the _id's of the associated Task and Task Workflow, which is a grouping of any Tasks needed to complete the request to the payroll system.

taskWorkflow._idstring: The _id of the Task Workflow.
taskWorkflow.tasks[0]._idstring: the _id of the Task.

Example response

{
  "data": {
    "taskWorkflow": {
      "_id": "6387e1eba1dabf6708a16e39",
      "tasks": [
        {
          "_id": "5eea76350d0ada0007fb43c7"
        }
      ]
    }
  }
}

Delete Deductions

Delete deductions which have been applied to employees by sending a list of deduction _id's to this PUT endpoint.

Authentication is handled via the API Key and Secret method. This API is intended to be called from your backend service so your API Keys and Secrets are not deployed to your client side application.

Required Properties

employeeDeductions[Employee Deduction]

The list of employee deductions to delete.

Child Properties

Required Properties

_idstring: The _id of the employee deduction to delete.

Optional Properties

trackingIdstring

A unique string that we store alongside your request, used to query the status of the deduction.

PUT/employers/:_id/delete-employee-deductions

https://sandbox-api.atomicfi.com/employers/:_id/delete-employee-deductions

Response

A successful request will return the _id's of the associated Task and Task Workflow, which is a grouping of any Tasks needed to complete the request to the payroll system.

taskWorkflow._idstring: The _id of the Task Workflow.
taskWorkflow.tasks[0]._idstring: the _id of the Task.

Example response

{
  "data": {
    "taskWorkflow": {
      "_id": "6387e1eba1dabf6708a16e39",
      "tasks": [
        {
          "_id": "5eea76350d0ada0007fb43c7"
        }
      ]
    }
  }
}

Payroll Runs

Get Payroll Runs

Authentication is handled via the API Key and Secret method. This API is intended to be called from your backend service so your API Keys and Secrets are not deployed to your client side application.

Required Properties

_idstring: The _id of the employer that the payroll runs belong to.

Optional Properties

nextCursorstring

The cursor to use to retrieve the next page of data.

previousCursorstring

The cursor to use to retrieve the previous page of data

limitinteger

The max number of employees to return.

checkDateAfterISO8601 Timestamp

ISO 8601 timestamp used for filtering payroll runs. Responses to API calls with this filter will include all payroll runs where the payroll check date is after the specified date.

checkDateBeforeISO8601 Timestamp

ISO 8601 timestamp used for filtering payroll runs. Responses to API calls with this filter will include all payroll runs where the payroll check date is before the specified date.

GET/employers/:_id/payroll-runs

https://sandbox-api.atomicfi.com/employers/:_id/payroll-runs

Response

A successful request will return a paginated list of payroll runs in ascending order of creation.

nextCursorstring: The cursor to use to get the next page of data. If null, the end of the data has been reached.
previousCursorstring: The cursor to use to get the previous page of data. If null, there is no previous page of data.
payrollRuns[PayrollRun]: An array of objects representing a payroll run. Each object will contain _id, employer, checkDate, payPeriodEndDate, payPeriodStartDate, runInitiatedDate, runType, and runState.

Example response

{
  "data": {
    "nextCursor": "6387dd18118deb05b68f0bde",
    "previousCursor": "6387dd0f1a5c71c793b4b507",
    "payrollRuns": [
      {
        "_id": "6407babd7d627e100e7a54d1",
        "employer": "6407bab97d627e100e7a5246",
        "checkDate": "2023-01-31T00:00:00.000Z",
        "payPeriodEndDate": "2023-01-16T00:00:00.000Z",
        "payPeriodStartDate": "2023-01-02T00:00:00.000Z",
        "runInitiatedDate": "2023-01-31T01:00:00.000Z",
        "runType": "regular",
        "runState": "approved"
      },
      {
        "_id": "6407babd7d627e100e7a54d2",
        "employer": "6407bab97d627e100e7a5246",
        "checkDate": "2022-11-30T00:00:00.000Z",
        "payPeriodEndDate": "2022-11-16T00:00:00.000Z",
        "payPeriodStartDate": "2022-11-02T00:00:00.000Z",
        "runInitiatedDate": "2022-11-30T01:00:00.000Z",
        "runType": "regular",
        "runState": "processed"
      }
    ]
  }
}

Get a Payroll Run

Authentication is handled via the API Key and Secret method. This API is intended to be called from your backend service so your API Keys and Secrets are not deployed to your client side application.

Required Properties

_idstring: The id of the payroll run.

GET/payroll-runs/:_id

https://sandbox-api.atomicfi.com/payroll-runs/:_id

Response

A successful request will return a payroll run, which contains a list of associated employee statements.

_idstring: The id of the employer document.
employerstring: The id of the employer.
checkDatedate: The date the payroll run was deposited, stored in UTC and ISO 8601 format.
payPeriodEndDatedate: The end date for the pay period of the payroll run, stored in UTC and ISO 8601 format.
payPeriodStartDatedate: The start date for the pay period of the payroll run, stored in UTC and ISO 8601 format.
runInitiatedDatedate: The date the payroll run was initiated, stored in UTl and ISO 8601 format.
runStatestring: The state of the payroll run. One of approved, closed, draft, failed, processed, or scheduled
runTypestring: The type of payroll run. One of accumulated-sick-leave, back-pay, bonus, commission, correction, off-cycle, one-time-payment, other, overtime, regular, sick-leave, termination, or travel-reimbursement
urlstring: The URL to download the raw payroll run document. Each request to this endpoint will generate a new URL, which will expire after 1 hour.
createdAtdate: The date the payroll run was initially retrieved.
updatedAtdate: The date the payroll run was most recently retrieved.
statements[]: List of statements that were a part of the payroll run

Example response

{
  "data": {
    "_id": "643980405d1c26218ba1eb75",
    "employer": "642c9aa6f8fc90e0dbb4c92f",
    "checkDate": "2023-04-14T16:45:16.243Z",
    "runInitiatedDate": "2022-11-30T01:00:00.000Z",
    "payPeriodStartDate": "2022-11-02T00:00:00.000Z",
    "payPeriodEndDate": "2022-11-16T00:00:00.000Z",
    "runState": "processed",
    "runType": "other",
    "url": "[ATOMIC-GENERATED-PRESIGNED-S3-URL]",
    "createdAt": "2023-04-14T16:33:04.736Z",
    "updatedAt": "2023-04-14T16:45:37.331Z",
    "statements": [
      {
        "_id": "6ccb35d2f66d4c0512f8magw",
        "employee": "5eea73d5f55d6c0007d1fcdf",
        "date": "2023-04-14T16:45:16.243Z",
        "payPeriodStartDate": "2022-11-02T00:00:00.000Z",
        "payPeriodEndDate": "2022-11-16T00:00:00.000Z",
        "grossAmount": 1000,
        "netAmount": 745,
        "deductions": [
          {
            "category": "taxes",
            "label": "Federal Income Tax",
            "rawLabel": "Federal Income Tax",
            "amount": 200,
            "ytdAmount": 2000
          },
          {
            "category": "taxes",
            "label": "State Income Tax",
            "rawLabel": "Utah State Tax",
            "amount": 50,
            "ytdAmount": 500
          },
          {
            "category": "other",
            "label": "Abc corp dd",
            "rawLabel": "Abc corp dd",
            "amount": 5,
            "ytdAmount": 50
          }
        ],
        "paystub": {
          "_id": "60abeff50836730008616fad",
          "url": "[ATOMIC-GENERATED-PRESIGNED-S3-URL]"
        }
      }
    ]
  }
}