
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
income
number- Employee's income, represented as a number.
incomeType
string- Employee's income type. Possible values are
yearly
,monthly
,weekly
,daily
, andhourly
. annualIncome
number- Employee's annual income, represented as a number. This value may be derived.
hourlyIncome
number- Employee's hourly income, represented as a number. This value may be derived.
netHourlyRate
number- Employees net hourly income, represented as a number. This value may be derived.
payCycle
string- How frequently the end user gets paid. Possible values are
monthly
,semimonthly
,biweekly
, andweekly
. This value may be derived. nextExpectedPayDate
date- Next expected paycheck date for the employee in ISO format. This value may be derived.
currentPayPeriodStart
date- The start date of the current pay period in ISO format. This value may be derived.
currentPayPeriodEnd
date- The end date of the current pay period in ISO format. This value may be derived.
unpaidHoursInPayPeriod
number- 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
, andpayPeriodEndDate
are available, depending on the statement provider.Child Properties
Optional Properties
date
stringDate of the deposit in ISO 8601 format.payPeriodStartDate
stringStarting date of the pay period in ISO 8601 format.payPeriodEndDate
stringEnding date of the pay period in ISO 8601 format.grossAmount
numberGross dollar amount of the deposit.ytdGrossAmount
numberYear to date gross dollar amount of the deposit.netAmount
numberNet dollar amount of the deposit.ytdNetAmount
numberYear to date net dollar amount of the deposit.paymentMethod
stringMethod used for the payment. Possible values includedeposit
orcheck
.hours
numberHours worked within the pay period.deductions
[Deduction]An array ofDeduction
objects, describing paycheck deductions such as taxes and benefits. Not all deductions will have bothamount
andytdAmount
available. We will extract all values available to us in the payroll system.Child Properties
Required Properties
category
string- Category of the deduction such as
taxes
,benefits
, orretirement
. rawLabel
string- The label for the deduction, exactly as given by the payroll provider.
label
string- A derived label for the deduction, if we think it matches a common deduction such as
Federal Income Tax
,Medicare
, orSocial Security
. The same asrawLabel
if we are unable to match a common deduction.
earnings
[Earnings]An array ofEarnings
objects, describing paycheck earnings such as bonuses and reimbursements. Not all earnings will have bothamount
andytdAmount
available. We will extract all values available to us in the payroll system.Child Properties
Required Properties
category
string- Category of the earning such as
benefit
,bereavement
,bonus
,commission
,disability
,holiday
,other
,overtime
,per diem
,reimbursement
,retropay
,sick
,tip
,vacation
, orwage
. rawLabel
string- The label for the earning, exactly as given by the payroll provider.
Optional Properties
amount
numberThe amount of the earning, in dollars, if provided by the payroll system.ytdAmount
numberThe year to date amount of the earning, in dollars, if provided by the payroll system.hours
numberThe number of hours used to calculate the total amount of the earning in this statement.rate
numberThe hourly rate of the earning, in dollars.netAmountAdjustments
[NetAmountAdjustment]paystub
objectAn object containing fields of_id
andurl
. Theurl
field can be used to download a PDF and is valid for 1 hour. If theurl
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,
"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]"
}
},
{
"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
accountNumber
string- Account number.
routingNumber
string- The ABA routing number.
type
string- Type of account. Possible values include
checking
,savings
, orpaycard
.
Optional Properties
bankName
stringThe name of the bank or financial institution providing the account.distributionType
stringThe type of distribution for the account. Possible values includetotal
,percent
, orfixed
.distributionAmount
numberThe amount being distributed to the account. WhendistributionType
ispercent
, the number represents a percentage of the total pay. WhendistributionType
isfixed
, this number represents a fixed dollar amount. This value is not set whendistributionType
istotal
.
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
employeeType
string- Employee type. Possible values are
contract
,parttime
, andfulltime
. employmentStatus
string- Employment status. Possible values are
active
andterminated
. This value may be derived. jobTitle
string- Employee's job title.
startDate
string- Employee's hire date.
minimumMonthsOfEmployment
number- The employee has been employed for at least this number of months. This value may be derived.
weeklyHours
number- Number of hours worked per week.
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
Optional Properties
totalWages
numberWages, tips and other compensation. Box 1 of the W-2 form.year
stringThe tax year.form
objectAn object containing fields of_id
andurl
. Theurl
field can be used to download a PDF and is valid for 1 hour. If theurl
expires, you can get a new one using the generate file URL endpoint.parsedData
objectAn object containing data parsed from the user's W-2 PDF.Child Properties
Optional Properties
taxYear
numberTax year on the W-2.employeeTin
stringEmployee's Social Security number or Individual Taxpayer Identification Number.employerTin
stringEmployer Identification Number (EIN).employerNameAddress
objectEmployer's name and address.Child Properties
Optional Properties
name1
stringName of the employer.line1
stringFirst line of the employer's address.line2
stringSecond line of the employer's address.line3
stringThird line of the employer's address.city
stringEmployer's address city.state
stringEmployer's address state.postalCode
stringEmployer's address postal code.controlNumber
stringBox D, control number.employeeName
objectemployeeAddress
objectEmployee's address.wages
numberBox 1, Wages, tips, other compensation.federalTaxWithheld
numberBox 2, Federal income tax withheld.socialSecurityWages
numberBox 3, Social security wages.socialSecurityTaxWithheld
numberBox 4, Social security tax withheld.medicareWages
numberBox 5, Medicare wages and tips.medicareTaxWithheld
numberBox 6, Medicare tax withheld.socialSecurityTips
numberBox 7, Social security tips.allocatedTips
numberBox 8, Allocated tips.dependentCareBenefit
numberBox 10, Dependent care benefits.nonQualifiedPlan
numberBox 11, Nonqualified plans.codes
[Codes]statutory
booleanBox 13, Statutory employee.retirementPlan
booleanBox 13, Retirement plan.thirdPartySickPay
booleanBox 13, Third-party sick pay.other
[Other]stateTaxWithholding
[State Tax Withholding]localTaxWithholding
[Local Tax Withholding]
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
firstName
string- First name.
lastName
string- Last name.
dateOfBirth
string- Date of birth in ISO 8601 format.
email
string- Email address.
phone
string- Phone number.
ssn
string- Social security number.
address
string- Street address of the user's address.
city
string- Address city.
state
string- Address state.
postalCode
string- 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
type
string- Type of timesheet entry is one of
paid
,unpaid
, orscheduled
. duration
number- The amount of time, in minutes.
date
string- The date of the timesheet entry in ISO 8601 format.
clockedIn
string- The ISO 8601 datetime string of when the user clocked in.
clockedOut
string- 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"
}
]
Derived Data
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": {
"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
}
]
}
}