Atomic logo
Employment data

Employment Data

Learn about the employment data that powers Atomic's products. Employment data is delivered to you via webhooks. For your convenience, the data may include both raw and derived fields.

incomenumber
Employee's income, represented as a number. This value may be derived.
incomeTypestring
Employee's income type. Possible values are `yearly`, `monthly`, `weekly`, `daily`, and `hourly`. This value may be derived.
annualIncomenumber
Employee's annual income, represented as a number. This value may be derived.
hourlyIncomenumber
Employee's hourly income, represented as a number. This value may be derived.
netHourlyRatenumber
Employees net hourly income, represented as a number. This value may be derived.
payCyclestring
How frequently the end user gets paid. Possible values are `monthly`, `semimonthly`, `biweekly`, and `weekly`. This value may be derived.
nextExpectedPayDatedate
Next expected paycheck date for the employee in ISO format. This value may be derived.
currentPayPeriodStartdate
The start date of the current pay period in ISO format. This value may be derived.
currentPayPeriodEnddate
The end date of the current pay period in ISO format. This value may be derived.
unpaidHoursInPayPeriodnumber
The number of hours the employee has worked in the current pay period. This is only available for hourly employees. This value may be derived.
Sample income data
{
  "income": 45000,
  "incomeType": "yearly",
  "annualIncome": 45000,
  "hourlyIncome": 21.56,
  "netHourlyRate": 18.44,
  "payCycle": "weekly",
  "nextExpectedPayDate": "2020-06-30T12:00:00.000Z",
  "currentPayPeriodStart": "2020-06-13T12:00:00.000Z",
  "currentPayPeriodEnd": "2020-06-27T12:00:00.000Z",
  "unpaidHoursInPayPeriod": 24
}
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
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
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.
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 deductions will have bothamount and ytdAmount available. We will extract all values available to us in the payroll system.
Child Properties
categorystring
Category of the earning such as bonus, commission, overtime, reimbursement, tip, or wage.
rawLabelstring
The label for the earning, exactly as given by the payroll provider.
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
labelstring
The label of the adjustment, exactly as given by the payroll provider.
amountnumber
The amount of the adjustment in dollars.
paystubobject
An object containing fields of _id and url. The url field can be used to download a PDF and is valid for 1 hour. If the url expires, you can get a new one using the generate file URL endpoint.
Sample statements data
{
  "statements": [
    {
      "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,
      "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": "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
        }
      ],
      "paystub": {
        "_id": "60abeff50836730008616fad",
        "url": "[ATOMIC-GENERATED-PRESIGNED-S3-URL]"
      }
    },
    {
      "date": "2020-06-30T12:00:00.000Z",
      "payPeriodStartDate": "2020-05-27T12:00:00.000Z",
      "payPeriodEndDate": "2020-06-12T12:00:00.000Z",
      "grossAmount": 1000,
      "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
        }
      ],
      "paystub": {
        "_id": "60abeff50836730008616fae",
        "url": "[ATOMIC-GENERATED-PRESIGNED-S3-URL]"
      }
    }
  ]
}
accounts[Account]
An array of deposit account objects.
Child Properties
accountNumberstring
Account number.
routingNumberstring
The ABA routing number.
typestring
Type of account. Possible values include checking, savings, or paycard.
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
    }
  ]
}
employeeTypestring
Employee type. Possible values are contract, parttime, and fulltime.
employmentStatusstring
Employment status. Possible values are `active` and `terminated`. This value may be derived.
jobTitlestring
Employee's job title.
startDatestring
Employee's hire date.
minimumMonthsOfEmploymentnumber
The employee has been employed for at least this number of months. This value may be derived.
weeklyHoursnumber
Number of hours worked per week.
employerobject
An object describing the employer.
Child Properties
namestring
Name of the employer.
addressobject
The employer's address.
Child Properties
line1string
First line of the employer's address.
line2string
Second line of the employer's address.
citystring
Address city.
statestring
Address state.
postalCodestring
Address postal code.
countrystring
Address country in ISO 3166 Alpha-3.
Sample employment data
{
  "employeeType": "fulltime",
  "employmentStatus": "active",
  "jobTitle": "Product Manager",
  "startDate": "2017-04-19T12:00:00.000Z",
  "minimumMonthsOfEmployment": 58,
  "weeklyHours": 40,
  "employer": {
    "name": "Company Inc.",
    "address": {
      "line1": "12345 Enterprise Rd",
      "line2": "Suite 105",
      "city": "Salt Lake City",
      "state": "UT",
      "postalCode": "84111",
      "country": "USA"
    }
  }
}
taxes[Tax]
An array of tax data objects.
Child Properties
typestring
The type of tax data. Possible values include w2 and 1099.
totalWagesnumber
Wages, tips and other compensation. Box 1 of the W2 form.
yearstring
The tax year.
formobject
An object containing fields of _id and url. The url field can be used to download a PDF and is valid for 1 hour. If the url expires, you can get a new one using the generate file URL endpoint.
Sample Tax data
{
  "taxes": [
    {
      "type": "w2",
      "year": "2020-01-01T00:00:00.000Z",
      "totalWages": 50000,
      "form": {
        "_id": "60abeff60836730008616faf",
        "url": "[ATOMIC-GENERATED-PRESIGNED-S3-URL]"
      }
    }
  ]
}
firstNamestring
First name.
lastNamestring
Last name.
dateOfBirthstring
Date of birth in ISO 8601 format.
emailstring
Email address.
phonestring
Phone number.
ssnstring
Social security number.
addressstring
Street address of the user's address.
citystring
Address city.
statestring
Address state.
postalCodestring
Address postal code.
Sample identity data
{
  "firstName": "Jane",
  "lastName": "Appleseed",
  "dateOfBirth": "1984-04-12T12:00:00.000Z",
  "email": "janeappleseed@example.com",
  "phone": "5558881111",
  "ssn": "111223333",
  "address": "123 Example St.",
  "city": "Salt Lake City",
  "state": "UT",
  "postalCode": "84111"
}
timesheets[Timesheet]
An array of Timesheet objects.
Child Properties
typestring
Type of timesheet entry is one of paid, unpaid, or scheduled.
durationnumber
The amount of time, in minutes.
datestring
The date of the timesheet entry.
Sample timesheet data
{
  "timesheets": [
    {
      "duration": 420,
      "date": "2021-10-13",
      "type": "unpaid",
      "calculated": true
    },
    {
      "duration": 480,
      "date": "2021-10-12",
      "type": "paid",
      "calculated": false
    },
    {
      "duration": 340,
      "date": "2021-10-11",
      "type": "paid",
      "calculated": false
    }
  ]
}

In cases where particular employment data is unavailable, their value may be algorithmically derived using surrounding data. Derived fields are indicated by the presence of their keys within the derivedOutputMetadata object which is a child of the data object, contained within webhook events. For reference, derivedOutputMetadata may also include additional information in the future regarding the method used to derive given data.

Sample data with derived outputs
{
  "derivedOutputMetadata": {
    "income": {},
    "incomeType": {},
    "annualIncome": {},
    "hourlyIncome": {},
    "netHourlyRate": {},
    "payCycle": {},
    "employmentStatus": {},
    "minimumMonthsOfEmployment": {},
    "nextExpectedPayDate": {},
    "currentPayPeriodStart": {},
    "currentPayPeriodEnd": {},
    "unpaidHoursInPayPeriod": {}
  },
  "outputs": {
    "income": 45154.92,
    "incomeType": "yearly",
    "annualIncome": 45154.92,
    "hourlyIncome": 21.64,
    "payCycle": "semimonthly",
    "employmentStatus": "terminated",
    "minimumMonthsOfEmployment": 1,
    "nextExpectedPayDate": "2020-06-30T12:00:00.000Z",
    "statements": [
      {
        "date": "2020-06-15T12:00:00.000Z",
        "payPeriodStartDate": "2020-05-27T12:00:00.000Z",
        "payPeriodEndDate": "2020-06-12T12:00:00.000Z",
        "grossAmount": 1875,
        "hours": 86.66
      },
      {
        "date": "2020-05-31T12:00:00.000Z",
        "payPeriodStartDate": "2020-05-11T12:00:00.000Z",
        "payPeriodEndDate": "2020-05-26T12:00:00.000Z",
        "grossAmount": 1875,
        "hours": 86.66
      }
    ]
  }
}