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.

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!

Income

incomenumber
Employee's income, represented as a number.
incomeTypestring
Employee's income type. Possible values are yearly, monthly, weekly, daily, and hourly.
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 which are to be paid out in the next pay cycle. 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

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
datestring
Date of the deposit in ISO 8601 format.
grossAmountnumber
Gross dollar amount of the deposit.
hoursnumber
Hours worked within the pay period.
netAmountnumber
Net dollar amount of the deposit.
payPeriodEndDatestring
Ending date of the pay period in ISO 8601 format.
payPeriodStartDatestring
Starting date of the pay period in ISO 8601 format.
ytdGrossAmountnumber
Year to date gross 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.
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.
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.
parsedDataobject
An object containing data parsed from the user's paystub PDF. This field is currently in Beta.
Child Properties
Optional Properties
datestring
Date of the deposit in ISO 8601 format.
grossAmountnumber
Gross dollar amount of the deposit.
hoursnumber
Hours worked within the pay period.
netAmountnumber
Net dollar amount of the deposit.
payPeriodEndDatestring
Ending date of the pay period in ISO 8601 format.
payPeriodStartDatestring
Starting date of the pay period in ISO 8601 format.
ytdGrossAmountnumber
Year to date gross dollar amount of the deposit.
ytdNetAmountnumber
Year to date net dollar amount of the deposit.
paymentMethodstring
Method used for the payment. These will be the raw value parsed from the paystub
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 PDF.
Child Properties
Optional Properties
categorystring
Category of the deduction.
rawLabelstring
The label for the deduction.
amountnumber
The amount of the deduction, in dollars.
ytdAmountnumber
The year to date amount of the deduction, in dollars.
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 pdf.
Child Properties
Required Properties
rawLabelstring
The label for the earning.
Optional Properties
categorystring
Category of the earning.
amountnumber
The amount of the earning, in dollars.
ytdAmountnumber
The year to date amount of the earning, in dollars.
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
rawLabelstring
The label of the adjustment.
amountnumber
The amount of the adjustment in dollars.
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,
      "paymentMethod": "deposit",
      "hours": 37,
      "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
        }
      ],
      "paystub": {
        "_id": "60abeff50836730008616fad",
        "url": "[ATOMIC-GENERATED-PRESIGNED-S3-URL]"
      },
      "parsedData": {
        "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": 37,
        "deductions": [
          {
            "category": "taxes",
            "rawLabel": "Federal Income Tax",
            "amount": 200,
            "ytdAmount": 2000
          },
          {
            "category": "taxes",
            "rawLabel": "Utah State Tax",
            "amount": 50,
            "ytdAmount": 500
          },
          {
            "category": "other",
            "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": [
          {
            "rawLabel": "Mileage Reimbursement",
            "amount": 25
          }
        ]
      }
    },
    {
      "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": 34,
      "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]"
      }
    }
  ]
}

Deposit Accounts

accounts[Deposit 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
    }
  ]
}

Employment

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
Optional Properties
namestring
Name of the employer.
addressobject
The employer's address.
Child Properties
Optional 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

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.
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.
parsedDataobject
An object containing data parsed from the user's W-2 PDF.
Child Properties
Optional Properties
taxYearnumber
Tax year on the W-2.
employeeTinstring
Employee's Social Security number or Individual Taxpayer Identification Number.
employerTinstring
Employer Identification Number (EIN).
employerNameAddressobject
Employer's name and address.
Child Properties
Optional Properties
name1string
Name of the employer.
line1string
First line of the employer's address.
line2string
Second line of the employer's address.
line3string
Third line of the employer's address.
citystring
Employer's address city.
statestring
Employer's address state.
postalCodestring
Employer's address postal code.
controlNumberstring
Box D, control number.
employeeNameobject
Employee name.
Child Properties
Optional Properties
firststring
First name.
laststring
Last name.
employeeAddressobject
Employee's address.
Child Properties
Optional Properties
line1string
First line of the employee's address.
line2string
Second line of the employee's address.
line3string
Third line of the employee's address.
citystring
Employee's address city.
statestring
Employee's address state.
postalCodestring
Employee's address postal code.
wagesnumber
Box 1, Wages, tips, other compensation.
federalTaxWithheldnumber
Box 2, Federal income tax withheld.
socialSecurityWagesnumber
Box 3, Social security wages.
socialSecurityTaxWithheldnumber
Box 4, Social security tax withheld.
medicareWagesnumber
Box 5, Medicare wages and tips.
medicareTaxWithheldnumber
Box 6, Medicare tax withheld.
socialSecurityTipsnumber
Box 7, Social security tips.
allocatedTipsnumber
Box 8, Allocated tips.
dependentCareBenefitnumber
Box 10, Dependent care benefits.
nonQualifiedPlannumber
Box 11, Nonqualified plans.
codes[Codes]
Box 12, Codes and amounts.
Child Properties
Optional Properties
codestring
Codes.
amountnumber
Amount.
statutoryboolean
Box 13, Statutory employee.
retirementPlanboolean
Box 13, Retirement plan.
thirdPartySickPayboolean
Box 13, Third-party sick pay.
other[Other]
Box 14, Other descriptions and amounts.
Child Properties
Optional Properties
descriptionstring
Description.
amountnumber
Amount.
stateTaxWithholding[State Tax Withholding]
Boxes 15-17, State tax withholding.
Child Properties
Optional Properties
stateTaxWithheldnumber
Amount of state income tax withheld.
statestring
State two-digit code.
stateTaxIdstring
Tax id of company withholding state income tax.
stateIncomenumber
Income amount for state tax purposes.
localTaxWithholding[Local Tax Withholding]
Boxes 18-20, Local tax withholding.
Child Properties
Optional Properties
localTaxWithheldnumber
Amount of local income tax withheld.
localityNamestring
Locality name.
statestring
State code of state in which locality exists.
localIncomenumber
Income amount for local tax purposes.
Sample Tax data 
{
  "taxes": [
    {
      "type": "w2",
      "year": "2020-01-01T00:00:00.000Z",
      "totalWages": 50000,
      "form": {
        "_id": "60abeff60836730008616faf",
        "url": "[ATOMIC-GENERATED-PRESIGNED-S3-URL]"
      },
      "parsedData": {
        "taxYear": 2022,
        "employeeTin": "XXX-XX-1234",
        "employerTin": "12-3456789",
        "employerNameAddress": {
          "name1": "Tax Form Issuer, Inc",
          "line1": "12021 Sunset Valley Dr",
          "city": "Preston",
          "state": "VA",
          "postalCode": "20191"
        },
        "controlNumber": "012547 WY/OA7",
        "employeeName": {
          "first": "Kris",
          "last": "Public"
        },
        "employeeAddress": {
          "line1": "1 Main St",
          "city": "Melrose",
          "state": "NY",
          "postalCode": "12121"
        },
        "wages": 44416.74,
        "federalTaxWithheld": 6907.16,
        "socialSecurityWages": 47162.92,
        "socialSecurityTaxWithheld": 2924.1,
        "medicareWages": 47162.92,
        "medicareTaxWithheld": 683.86,
        "socialSecurityTips": 134.25,
        "allocatedTips": 149.75,
        "dependentCareBenefit": 543.25,
        "nonQualifiedPlan": 354.23,
        "codes": [
          {
            "code": "C",
            "amount": 301.5
          },
          {
            "code": "D",
            "amount": 2746.18
          },
          {
            "code": "DD",
            "amount": 4781.88
          }
        ],
        "other": [
          {
            "description": "Housing",
            "amount": 6500
          },
          {
            "description": "Union Dues",
            "amount": 1500
          }
        ],
        "stateTaxWithholding": [
          {
            "stateTaxWithheld": 1726.78,
            "state": "OH",
            "stateTaxId": "OH 036-133505158F-01",
            "stateIncome": 44416.74
          }
        ],
        "localTaxWithholding": [
          {
            "localTaxWithheld": 427.62,
            "localityName": "Kirtland",
            "state": "OH",
            "localIncome": 44416.74
          }
        ]
      }
    }
  ]
}

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.
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

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 in ISO 8601 format.
clockedInstring
The ISO 8601 datetime string of when the user clocked in.
clockedOutstring
The ISO 8601 datetime string of when the user clocked out.
Sample timesheet data 
[
  {
    "duration": 420,
    "date": "2021-10-13T12:00:00.000Z",
    "type": "unpaid",
    "clockedIn": "2021-10-13T13:00:00.000Z",
    "clockedOut": "2021-10-13T20:00:00.000Z"
  },
  {
    "duration": 480,
    "date": "2021-10-12T12:00:00.000Z",
    "type": "paid",
    "clockedIn": "2021-10-12T13:00:00.000Z",
    "clockedOut": "2021-10-12T21:00:00.000Z"
  },
  {
    "duration": 340,
    "date": "2021-10-11T12:00:00.000Z",
    "type": "paid",
    "clockedIn": "2021-10-11T13:00:00.000Z",
    "clockedOut": "2021-10-11T18:40:00.000Z"
  }
]

Output Metadata

The outputMetadata object will serve to replace and enhance the derivedOutputMetadata object, which is now deprecated and will be fully sunset in the future.

This object contains information on how each field of the outputs object was obtained. Each key of the outputMetadata object will correspond to a field in the outputs object using path based notation for nested fields. The value of each key will contain an object with a key sourcedFrom. The value of sourcedFrom will be one of: api, web, paystub, or derived.

When the outputMetadata object is not present, it is assumed that the fields are sourced via api or web. The outputMetadata object will be included as a child of the data object, contained within the webhook events for that Task.

Sample data with output metadata 
{
  "outputMetadata": {
    "annualIncome": {
      "sourcedFrom": "derived"
    },
    "paycyle": {
      "sourcedFrom": "derived"
    },
    "statements.0.grossAmount": {
      "sourcedFrom": "paystub"
    }
  },
  "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
      }
    ]
  },
  "derivedOutputMetadata": {
    "annualIncome": {},
    "hourlyIncome": {},
    "netHourlyRate": {},
    "payCycle": {},
    "employmentStatus": {},
    "minimumMonthsOfEmployment": {},
    "nextExpectedPayDate": {},
    "currentPayPeriodStart": {},
    "currentPayPeriodEnd": {},
    "unpaidHoursInPayPeriod": {}
  }
}