Pay stub
Pay stubs work a little differently
Due to the bespoke nature of pay stubs, we do not support the
PAYSTUB
form type on any of the Form data endpoints. Please use one of the Pay stub data endpoints instead.
PayStub
PayStub
A representation of the data we've extracted from a given pay stub.
Learn more about how we process pay stubs here.
Properties
Name | Type | Description |
---|---|---|
uuid | string(uuid) | ID for the Paystub |
book_uuid | string(uuid) | ID for the Book containing the Paystub |
doc_uuid | string(uuid) | ID for the document containing the Paystub |
doc_page_numbers | [integer] | Pay stub page number according to order of pages at the time of upload |
uploaded_image_bucket_uuid | string(uuid) | |
employer | Employer | |
employee | Employee | |
employment_details | EmploymentDetails | |
paystub_details | PayStubDetails | |
net_pay | NetPay | |
earnings | Earnings | |
deductions | Deductions |
Employer
Employer
Properties
Name | Type | Description |
---|---|---|
name | string¦null | |
address | Address |
Employee
Employee
Properties
Name | Type | Description |
---|---|---|
name | string | |
address | Address | |
marital_status | string¦null | Tax filing status if printed on the pay stub |
taxpayer_id | TaxpayerId |
Enumerated Values
Property | Value |
---|---|
marital_status | MARRIED |
marital_status | SINGLE |
marital_status | NOT LISTED |
EmploymentDetails
EmploymentDetails
Properties
Enumerated Values
Property | Value |
---|---|
pay_basis | HOURLY |
pay_basis | SALARY |
pay_basis | OTHER |
pay_basis | NOT LISTED |
PayStubDetails
PayStubDetails
Properties
Name | Type | Description |
---|---|---|
pay_period_start_date | string(date)¦null | |
pay_period_end_date | string(date)¦null | |
pay_date | string(date)¦null | |
paystub_provider | string¦null | |
pay_frequency | string¦null | system-calculated pay frequency when both pay_period_start_date and pay_period_end_date are explicitly present in the document |
pay_frequency_captured | string¦null | The explicit pay frequency as printed on the paystub. |
Enumerated Values
Property | Value |
---|---|
pay_frequency | MONTHLY |
pay_frequency | BI_WEEKLY |
pay_frequency | WEEKLY |
pay_frequency | SEMI_MONTHLY |
pay_frequency_captured | WEEKLY |
pay_frequency_captured | BI-WEEKLY |
pay_frequency_captured | SEMI-MONTHLY |
pay_frequency_captured | MONTHLY |
pay_frequency_captured | NOT LISTED |
NetPay
NetPay
Properties
Name | Type | Description |
---|---|---|
distribution_details | [PayDistribution] | |
totals | Total |
PayDistribution
PayDistribution
Properties
Name | Type | Description |
---|---|---|
description | string¦null | |
bank_name | string¦null | |
account_number | string¦null | |
bank_account_type | string¦null | |
current_pay | numerical¦null |
Earnings
Earnings
Properties
Name | Type | Description |
---|---|---|
sub_totals | [EarningsSubtotal] | |
totals | [EarningsTotal] |
Deductions
Deductions
Properties
Total
Total
Properties
Name | Type | Description |
---|---|---|
description | string¦null | Text of the line item as printed on the pay stub |
canonical_description | CanonicalPayStubDescription | Commonly used term to describe the line item, e.g. Social Security Employee Tax NULL value is provided when a line item is not recognized by Ocrolus. |
current_pay | numerical¦null | |
ytd_pay | numerical¦null |
EarningsTotal
EarningsTotal
Properties
allOf
Name | Type | Description |
---|---|---|
*anonymous* | Total |
and
Name | Type | Description |
---|---|---|
*anonymous* | object | |
» current_hours | number |
EarningsSubtotal
EarningsSubtotal
Properties
allOf
Name | Type | Description |
---|---|---|
*anonymous* | EarningsTotal |
and
Name | Type | Description |
---|---|---|
*anonymous* | object | |
» current_rate | number |
Address
Address
Properties
Name | Type | Description |
---|---|---|
line1 | string¦null | Address Line 1 |
line2 | string¦null | Address Line 2 |
city | string¦null | City |
state_code | string¦null | Usually a two-letter state code |
postal_code | string¦null | Usually a 5-digit postal code |
TaxpayerId
TaxpayerId
The identity of a person who pays taxes. Usually, it will be a social security number, but not always.
Properties
Name | Type | Description |
---|---|---|
id_type | string¦null | Type of ID, e.g. 'SSN' |
last_4_digits | string¦null | Last 4 digits of unique number of ID |
Number
Number
It usually represents US dollars.
Properties
Name | Type | Description |
---|---|---|
amount | numerical¦null | Numerical value most likely has at least two decimal digits |
currency | string¦null | Example: USD |
CanonicalPayStubDescription
CanonicalPayStubDescription
Because pay stubs don't follow a standard format in the same way that tax forms do, different pay stubs may offer their own names for the same concept. Ocrolus is able to link common terms identified on pay stubs to a canonical description. Given below is the library of terms found on pay stubs that Ocrolus recognizes and maps to a canonical form field value.
If we couldn't map a pay stub entry to one of the aforementioned canonical names, then its canonical_description
field in the returned object will be null
. If you believe such an entry should have an alias or its own canonical description, please contact us with details about your use case.
Enumerated Values
Any use of CanonicalPayStubDescription
refers to any of the below values. They are listed as earnings and deductions for convenience.
Earnings
Value | Description |
---|---|
Allowance | Any other allowance or stipend aside from Per Diem |
Bereavement | Bereavement leave earnings |
Bonus | Bonus earnings besides retention, signing and referral bonuses |
Commission | Commission earnings |
Holiday Pay | Holiday earnings |
Jury Duty | Jury duty earnings |
Leave | Leave earnings that don't fit one of these other descriptions |
Long Term Disability Pay | Long term disability earnings |
Military Pay | BAS, BAH, BAF |
Overtime | Overtime earnings |
Paid Time Off | Paid time off earnings |
Per Diem | Daily allowance and compensation earnings |
Referral Bonus | Referral award compensation |
Regular Pay | Total base pay earnings |
Reimbursements | Any reimbursement if added to earnings |
Retention Bonus | Retention award compensation |
Retroactive/Back Pay | Compensation earned from previous pay periods |
Severance Pay | Compensation for termination of employment |
Shift Differential | Additional earnings for working outside normal business hours |
Short Term Disability Pay | Short-term disability earnings |
Sick Pay | Sick pay earnings |
Signing Bonus | Sign-on award compensation |
Tips Income | Tips earnings |
Vacation | Vacation earnings |
Deductions
Deductions from the pay stub
Value | Description |
---|---|
401k | Both pre-tax and post-tax 401k deductions |
Alimony | Alimony payments deducted from the employee's pay |
Child Support | Child support payments deducted from the employee's pay |
City/County Tax | Any city or county tax withholdings |
Dental | Dental insurance deductions |
Disability Tax | Includes both pre-tax and post-tax disability tax deductions |
Dues | Miscellaneous dues deducted from gross pay (e.g. Union Dues, Uniform Dues) |
Employee Medicare | Medicare tax withholdings |
FICA | Combined Social Security and Medicare tax withholdings |
Federal Withholdings | Federal tax withholdings |
Garnishments | Any wage garnishments besides Child Support or Alimony |
Health Savings Account/HSA/FSA | Health savings account and flexible spending account contributions |
Investments | Broad category for retirement plans and other investments except for 401k deductions (e.g. IRA, Pension, STRS) |
Life Insurance | Explicitly stated as life insurances including accidental death and dismemberment insurance |
Loan | Any loan payment deducted from employee's earnings |
Long Term Disability | Long-term disability insurance deductions |
Medical | Medical insurance deductions (e.g. Medical Insurance, Critical Illness Insurance, Cancer Insurance) |
Short Term Disability | Short-term disability insurance deductions |
Social Security Employee Tax | Social security tax withholdings |
State Tax | State tax withholdings |
Vision | Vision insurance deductions |
Sample pay stub
The below Ocrolus Sample PDF (input) matches the below sample JSON result (output).
Sample JSON response
{
"book_uuid": "69d1673c-9c30-4e1a-8f0e-5758e12b1f13",
"uploaded_image_bucket_uuid": null,
"doc_uuid": "7b662595-e811-4548-9a2a-e76dd6ffbd07",
"doc_page_numbers": [
1
],
"uuid": "3fdbf4ea-097a-47e0-bc20-1f32a265ef3d",
"employer": {
"name": "INSTANT CARD NATIONAL",
"address": {
"line1": "2712 WHITE RIVER AVE.",
"line2": null,
"city": "OAKLAND",
"state_code": "CA",
"postal_code": "94621"
}
},
"employee": {
"name": "TAMIKA S. NOTE",
"address": {
"line1": "4654 SYCAMORE ST.",
"line2": null,
"city": "SAN JOSE",
"state_code": "CA",
"postal_code": "95113"
},
"marital_status": "SINGLE",
"taxpayer_id": {
"id_type": "SSN",
"last_4_digits": "2323"
}
},
"employment_details": {
"hire_date": null,
"annual_salary": {
"amount": null,
"currency": null
},
"pay_basis": null,
"hourly_rate": {
"amount": null,
"currency": null
}
},
"paystub_details": {
"pay_period_start_date": "2022-03-04",
"pay_period_end_date": "2022-03-17",
"pay_date": "2022-03-18",
"paystub_provider": null,
"pay_frequency": "BI_WEEKLY",
"pay_frequency_captured": "NOT LISTED"
},
"net_pay": {
"distribution_details": [
{
"description": "UNION CREDIT BANK SAVINGS 5252",
"bank_name": "UNION CREDIT BANK",
"account_number": "5252",
"bank_account_type": "SAVINGS",
"current_pay": {
"amount": "100.00",
"currency": "USD"
}
},
{
"description": "FEDERAL CREDIT UNION CHECKING 3328",
"bank_name": "FEDERAL CREDIT UNION",
"account_number": "3328",
"bank_account_type": "CHECKING",
"current_pay": {
"amount": "863.60",
"currency": "USD"
}
}
],
"totals": {
"description": "NET PAY",
"canonical_description": null,
"current_pay": {
"amount": "963.60",
"currency": "USD"
},
"ytd_pay": {
"amount": "8952.65",
"currency": "USD"
}
}
},
"earnings": {
"subtotals": [
{
"description": "REGULAR",
"canonical_description": "REGULAR PAY",
"current_pay": {
"amount": "1600.00",
"currency": "USD"
},
"ytd_pay": {
"amount": "9600.00",
"currency": "USD"
},
"current_hours": "80.00",
"current_rate": "20.00"
},
{
"description": "ANNUAL BONUS",
"canonical_description": "BONUS",
"current_pay": {
"amount": "0.00",
"currency": "USD"
},
"ytd_pay": {
"amount": "5250.00",
"currency": "USD"
},
"current_hours": null,
"current_rate": null
}
],
"totals": [
{
"description": "GROSS PAY",
"canonical_description": null,
"current_pay": {
"amount": "1600.00",
"currency": "USD"
},
"ytd_pay": {
"amount": "14850.00",
"currency": "USD"
},
"current_hours": null
}
]
},
"deductions": {
"subtotals": [
{
"description": "HEALTH PLAN",
"canonical_description": "MEDICAL",
"current_pay": {
"amount": "46.00",
"currency": "USD"
},
"ytd_pay": {
"amount": "417.66",
"currency": "USD"
}
},
{
"description": "FEDERAL TAX",
"canonical_description": "FEDERAL WITHHOLDINGS",
"current_pay": {
"amount": "352.00",
"currency": "USD"
},
"ytd_pay": {
"amount": "3267.00",
"currency": "USD"
}
},
{
"description": "SOCIAL SECURITY",
"canonical_description": "SOCIAL SECURITY EMPLOYEE TAX",
"current_pay": {
"amount": "99.20",
"currency": "USD"
},
"ytd_pay": {
"amount": "920.70",
"currency": "USD"
}
},
{
"description": "MEDICARE",
"canonical_description": "EMPLOYEE MEDICARE",
"current_pay": {
"amount": "23.20",
"currency": "USD"
},
"ytd_pay": {
"amount": "215.36",
"currency": "USD"
}
},
{
"description": "STATE TAX",
"canonical_description": "STATE TAX",
"current_pay": {
"amount": "116.00",
"currency": "USD"
},
"ytd_pay": {
"amount": "1076.63",
"currency": "USD"
}
}
],
"totals": [
{
"description": "DEDUCTIONS",
"canonical_description": null,
"current_pay": {
"amount": "636.40",
"currency": "USD"
},
"ytd_pay": {
"amount": "5897.35",
"currency": "USD"
}
}
]
},
"status": "COMPLETED",
"rejection_reason": null
}
Updated 5 days ago