Employment data

EmployerLink Employment Data

Learn about the employment data that powers Atomic's products. Employment data is delivered to you via webhooks, or you can pull the data via our API.

Be sure to check out our new Coverage Explorer to see coverage across our payroll integrations and what data fields we have to support your use case!

Deposit Accounts

accounts[Account]
An array of deposit account objects.
Child Properties
Required Properties
accountNumberstring
Account number.
routingNumberstring
The ABA routing number.
typestring
Type of account. Possible values include checking, savings, or paycard.
Optional Properties
bankNamestring
The name of the bank or financial institution providing the account.
distributionTypestring
The type of distribution for the account. Possible values include total, percent, or fixed.
distributionAmountnumber
The amount being distributed to the account. When distributionType is percent, the number represents a percentage of the total pay. When distributionType is fixed, this number represents a fixed dollar amount. This value is not set when distributionType is total.
Sample deposit account data 
{
  "accounts": [
    {
      "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
    }
  ]
}

Employee Deductions

employeeDeductions[Employee Deductions]
An array of employee deduction objects, each containing information about the deductions on file for a specific employee.
Child Properties
Required Properties
_idstring
The _id of the deduction in Atomic's system.
createdAtstring
The date the deduction was first fetched from the payroll system in ISO 8601 format.
updatedAtstring
The date the deduction was most recently fetched from the payroll system in ISO 8601 format.
employeestring
The _id of the employee the deduction belongs to.
labelstring
The label is a string stored in the payroll sytem to help identify a deduction. If you need to match on specific enumerated categories used by the payroll systems, use the category property instead.
amountnumber
Amount of the deduction. Can be a percentage or a fixed dollar amount depending on the value of calculation
calculationstring
One of percent or fixed.
Optional Properties
startDatestring
Starting date of the deduction in ISO 8601 format.
endDatestring
Ending date of the deduction in ISO 8601 format.
categorystring
One of pre-tax, 401k, 401k-catchup, 403b, 408b, 408k, premium-only-plan, garnishment or other.
categoryTypestring
One of pre-tax or post-tax.
Sample employee deductions data 
{
  "employeeDeductions": [
    {
      "_id": "642703b666b8c0abb8c65cff",
      "createdAt": "2023-08-14T20:04:17.459Z",
      "updatedAt": "2023-08-14T20:29:45.917Z",
      "employee": "642c9aa6f8fc90e0dbb4c92f",
      "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"
    },
    {
      "_id": "642703b666b8c0abb8c65d01",
      "createdAt": "2023-08-14T20:04:17.459Z",
      "updatedAt": "2023-08-14T20:29:45.917Z",
      "employee": "642c9aa6f8fc90e0dbb4c92f",
      "label": "Life Insurance",
      "amount": 100,
      "calculation": "fixed",
      "category": "Other"
    }
  ]
}

Employment

employeeTypestring
Type of employment for the specified employee. Possible values are contract, fulltime, intern, parttime, seasonal, student, and temporary.
employmentStatusstring
Status of employment for specified employee. Possible values are active and terminated.
jobTitlestring
Employee's job title.
startDatestring
Employee's hire date.
weeklyHoursnumber
Number of hours worked per week.
classCodestring
The class code of the employee.
terminationDatestring
Optional. Date employee's employment was terminated.
Sample employment data 
{
  "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"
}

Identity

firstNamestring
First name.
lastNamestring
Last name.
dateOfBirthstring
Date of birth in ISO 8601 format.
emailstring
Email address.
phonestring
Phone number.
ssnstring
Social security number.
homeAddressobject
Object containing all fields for an employees home address.
Child Properties
Optional Properties
line1string
String containing the first line of the employees's address.
line2string
String containing the second line of the employees's address, if applicable.
citystring
Address city.
statestring
Address state.
zipcodestring
Address zip code.
countrystring
Address country.
Sample identity data 
{
  "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

incomenumber
Employee's income, represented as a number.
incomeTypestring
Employee's income type. Possible values are yearly, monthly, weekly, daily, and hourly.
payCyclestring
How frequently the end user gets paid. Possible values are monthly, semimonthly, biweekly, and weekly.
Sample income data 
{
  "income": 45000,
  "incomeType": "yearly",
  "payCycle": "weekly"
}

Statements

statements[Statement]
An array of statement objects. For date fields, we will return whichever of date, payPeriodStartDate, and payPeriodEndDate are available, depending on the statement provider.
Child Properties
Optional Properties
_idstring
The id of the statement in Atomic's system.
createdAtstring
The date the statement was first fetched from the payroll system in ISO 8601 format.
updatedAtstring
The date the statement was most recently fetched from the payroll system in ISO 8601 format.
employeestring
The _id of the employee the statement belongs to.
datestring
Date of the deposit in ISO 8601 format.
payPeriodStartDatestring
Starting date of the pay period in ISO 8601 format.
payPeriodEndDatestring
Ending date of the pay period in ISO 8601 format.
grossAmountnumber
Gross dollar amount of the deposit.
ytdGrossAmountnumber
Year to date gross dollar amount of the deposit.
netAmountnumber
Net dollar amount of the deposit.
ytdNetAmountnumber
Year to date net dollar amount of the deposit.
paymentMethodstring
Method used for the payment. Possible values include deposit or check.
hoursnumber
Hours worked within the pay period.
deductions[Deduction]
An array of Deduction objects, describing paycheck deductions such as taxes and benefits. Not all deductions will have bothamount and ytdAmount available. We will extract all values available to us in the payroll system.
Child Properties
Required Properties
categorystring
Category of the deduction such as taxes, benefits, or retirement.
rawLabelstring
The label for the deduction, exactly as given by the payroll provider.
labelstring
A derived label for the deduction, if we think it matches a common deduction such as Federal Income Tax, Medicare, or Social Security. The same as rawLabel if we are unable to match a common deduction.
Optional Properties
amountnumber
The amount of the deduction, in dollars, if provided by the payroll system.
ytdAmountnumber
The year to date amount of the deduction, in dollars, if provided by the payroll system.
earnings[Earnings]
An array of Earnings objects, describing paycheck earnings such as bonuses and reimbursements. Not all earnings will have bothamount and ytdAmount available. We will extract all values available to us in the payroll system.
Child Properties
Required Properties
categorystring
Category of the earning such as benefit, bereavement, bonus, commission, disability, holiday, other, overtime, per diem, reimbursement, retropay, sick, tip, vacation, or wage.
rawLabelstring
The label for the earning, exactly as given by the payroll provider.
Optional Properties
amountnumber
The amount of the earning, in dollars, if provided by the payroll system.
ytdAmountnumber
The year to date amount of the earning, in dollars, if provided by the payroll system.
hoursnumber
The number of hours used to calculate the total amount of the earning in this statement.
ratenumber
The hourly rate of the earning, in dollars.
netAmountAdjustments[NetAmountAdjustment]
An array of NetAmountAdjustment objects, describing positive paycheck adjustments such as reimbursements.
Child Properties
Optional Properties
labelstring
The label of the adjustment, exactly as given by the payroll provider.
amountnumber
The amount of the adjustment in dollars.
Sample statements data 
{
  "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

taxes[Tax]
An array of tax data objects.
Child Properties
Required Properties
typestring
The type of tax data. Possible values include w2 and 1099.
Optional Properties
totalWagesnumber
Wages, tips and other compensation. Box 1 of the W-2 form.
yearstring
The tax year.
Sample Tax data 
{
  "taxes": [
    {
      "type": "w2",
      "year": "2020-01-01T00:00:00.000Z",
      "totalWages": 50000
    },
    {
      "type": "w2",
      "year": "2021-01-01T00:00:00.000Z",
      "totalWages": 55000
    }
  ]
}