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.
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.
{
"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.grossAmount
numberGross dollar amount of the deposit.hours
numberHours worked within the pay period.netAmount
numberNet dollar amount of the deposit.payPeriodEndDate
stringEnding date of the pay period in ISO 8601 format.payPeriodStartDate
stringStarting date of the pay period in ISO 8601 format.ytdGrossAmount
numberYear to date gross 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
.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.parsedData
objectAn object containing data parsed from the user's paystub PDF. This field is currently in Beta.Child Properties
Optional Properties
date
stringDate of the deposit in ISO 8601 format.grossAmount
numberGross dollar amount of the deposit.hours
numberHours worked within the pay period.netAmount
numberNet dollar amount of the deposit.payPeriodEndDate
stringEnding date of the pay period in ISO 8601 format.payPeriodStartDate
stringStarting date of the pay period in ISO 8601 format.ytdGrossAmount
numberYear to date gross dollar amount of the deposit.ytdNetAmount
numberYear to date net dollar amount of the deposit.paymentMethod
stringMethod used for the payment. These will be the raw value parsed from the paystubdeductions
[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 PDF.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 pdf.Child Properties
Optional Properties
category
stringCategory of the earning.amount
numberThe amount of the earning, in dollars.ytdAmount
numberThe year to date amount of the earning, in dollars.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.
{
"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
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
.
{
"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.
{
"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]
{
"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.
{
"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.
[
{
"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.
{
"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": {}
}
}