🚧

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

A representation of the data we've extracted from a given pay stub.

Learn more about how we process pay stubs here.

Properties

NameTypeDescription
uuidstring(uuid)ID for the Paystub
book_uuidstring(uuid)ID for the Book containing the Paystub
doc_uuidstring(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_uuidstring(uuid)
employerEmployer
employeeEmployee
employment_detailsEmploymentDetails
paystub_detailsPayStubDetails
net_payNetPay
earningsEarnings
deductionsDeductions

Employer

Properties

NameTypeDescription
namestring¦null
addressAddress

Employee

Properties

NameTypeDescription
namestring
addressAddress
marital_statusstring¦nullTax filing status if printed on the pay stub
taxpayer_idTaxpayerId

Enumerated Values

PropertyValue
marital_statusMARRIED
marital_statusSINGLE
marital_statusNOT LISTED

EmploymentDetails

Properties

NameTypeDescription
hire_datestring(date)¦null
annual_salarynumerical¦null
pay_basisstring¦nullThe explicit pay basis if present on the pay stub
hourly_ratenumerical¦nullIf a value is explicitly present on pay stub summary outside of the earnings table

Enumerated Values

PropertyValue
pay_basisHOURLY
pay_basisSALARY
pay_basisOTHER
pay_basisNOT LISTED

PayStubDetails

Properties

NameTypeDescription
pay_period_start_datestring(date)¦null
pay_period_end_datestring(date)¦null
pay_datestring(date)¦null
paystub_providerstring¦null
pay_frequencystring¦nullsystem-calculated pay frequency when both pay_period_start_date and pay_period_end_date are explicitly present in the document
pay_frequency_capturedstring¦nullThe explicit pay frequency as printed on the paystub.

Enumerated Values

PropertyValue
pay_frequencyMONTHLY
pay_frequencyBI_WEEKLY
pay_frequencyWEEKLY
pay_frequencySEMI_MONTHLY
pay_frequency_capturedWEEKLY
pay_frequency_capturedBI-WEEKLY
pay_frequency_capturedSEMI-MONTHLY
pay_frequency_capturedMONTHLY
pay_frequency_capturedNOT LISTED

NetPay

Properties

NameTypeDescription
distribution_details[PayDistribution]
totalsTotal

PayDistribution

Properties

NameTypeDescription
descriptionstring¦null
bank_namestring¦null
account_numberstring¦null
bank_account_typestring¦null
current_paynumerical¦null

Earnings

Properties

NameTypeDescription
sub_totals[EarningsSubtotal]
totals[EarningsTotal]

Deductions

Properties

NameTypeDescription
sub_totals[Total]
totals[Total]

Total

Properties

NameTypeDescription
descriptionstring¦nullText of the line item as printed on the pay stub
canonical_descriptionCanonicalPayStubDescriptionCommonly 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_paynumerical¦null
ytd_paynumerical¦null

EarningsTotal

Properties

allOf

NameTypeDescription
*anonymous*Total

and

NameTypeDescription
*anonymous*object
» current_hoursnumber

EarningsSubtotal

Properties

allOf

NameTypeDescription
*anonymous*EarningsTotal

and

NameTypeDescription
*anonymous*object
» current_ratenumber

Address

Properties

NameTypeDescription
line1string¦nullAddress Line 1
line2string¦nullAddress Line 2
citystring¦nullCity
state_codestring¦nullUsually a two-letter state code
postal_codestring¦nullUsually a 5-digit postal code

TaxpayerId

The identity of a person who pays taxes. Usually, it will be a social security number, but not always.

Properties

NameTypeDescription
id_typestring¦nullType of ID, e.g. 'SSN'
last_4_digitsstring¦nullLast 4 digits of unique number of ID

Number

It usually represents US dollars.

Properties

NameTypeDescription
amountnumerical¦nullNumerical value most likely has at least two decimal digits
currencystring¦nullExample: USD

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

ValueDescription
AllowanceAny other allowance or stipend aside from Per Diem
BereavementBereavement leave earnings
BonusBonus earnings besides retention, signing and referral bonuses
CommissionCommission earnings
Holiday PayHoliday earnings
Jury DutyJury duty earnings
LeaveLeave earnings that don't fit one of these other descriptions
Long Term Disability PayLong term disability earnings
Military PayBAS, BAH, BAF
OvertimeOvertime earnings
Paid Time OffPaid time off earnings
Per DiemDaily allowance and compensation earnings
Referral BonusReferral award compensation
Regular PayTotal base pay earnings
ReimbursementsAny reimbursement if added to earnings
Retention BonusRetention award compensation
Retroactive/Back PayCompensation earned from previous pay periods
Severance PayCompensation for termination of employment
Shift DifferentialAdditional earnings for working outside normal business hours
Short Term Disability PayShort-term disability earnings
Sick Pay Sick pay earnings
Signing BonusSign-on award compensation
Tips IncomeTips earnings
VacationVacation earnings

Deductions

Deductions from the pay stub

ValueDescription
401kBoth pre-tax and post-tax 401k deductions
AlimonyAlimony payments deducted from the employee's pay
Child SupportChild support payments deducted from the employee's pay
City/County TaxAny city or county tax withholdings
DentalDental insurance deductions
Disability TaxIncludes both pre-tax and post-tax disability tax deductions
DuesMiscellaneous dues deducted from gross pay (e.g. Union Dues, Uniform Dues)
Employee MedicareMedicare tax withholdings
FICACombined Social Security and Medicare tax withholdings
Federal WithholdingsFederal tax withholdings
GarnishmentsAny wage garnishments besides Child Support or Alimony
Health Savings Account/HSA/FSAHealth savings account and flexible spending account contributions
InvestmentsBroad category for retirement plans and other investments except for 401k deductions (e.g. IRA, Pension, STRS)
Life InsuranceExplicitly stated as life insurances including accidental death and dismemberment insurance
LoanAny loan payment deducted from employee's earnings
Long Term DisabilityLong-term disability insurance deductions
MedicalMedical insurance deductions (e.g. Medical Insurance, Critical Illness Insurance, Cancer Insurance)
Short Term DisabilityShort-term disability insurance deductions
Social Security Employee TaxSocial security tax withholdings
State TaxState tax withholdings
VisionVision 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
}