Our pay stub capture lets you make informed decisions involving a prospective borrower's recent income history. We identify and categorize the earnings and deductions listed on a pay stub, separating recurring base pay from one-time bonuses or commissions. Finally, the net pay distribution allows you to compare deposit amounts against bank statement transactions, giving you confidence in your lending decision.

🚧

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.

Usage guide

Here's how you can capture data from a pay stub:

  1. If you haven't already, create a Book to hold the documents you'd like to capture.
  2. Upload a pay stub to the Book with one of the following methods:
  3. Once the pay stub is processed, you can retrieve the captured data with one of the following methods:
    • You can retrieve a specific pay stub's captured data by calling this endpoint with its UUID.
    • You can retrieve the captured data for all pay stubs in a Book by providing the Book's UUID to this endpoint.

You can use webhook notifications to be immediately notified when we finish processing the pay stub. You can also poll the aforementioned endpoints.

Pay stub data structure

The pay stub full extraction output diagram is below.

The composite data type Pay stub, consists of several fields and composite data types. The items in blue denote a composite data type; for example, the Net Pay object consists of an array of Pay Distribution objects and a single Total object.

Details about the composite data structures can be found on the Pay stub composite data type page. You can find sample documents there as well.

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 the order of pages at the time of upload.
uploaded_image_bucket_uuidstring(uuid)A unique identifier for the storage location (bucket) where uploaded images are stored
employerEmployerName of the employer
employeeEmployeeName of the employee
employment_detailsEmploymentDetailsDetails of the employee
paystub_detailsPayStubDetailsEmployee's pay stub details
net_payNetPayNet pay amount
earningsEarningsTotal earnings
deductionsDeductionsTotal deductions

Employer

Properties

NameTypeDescription
namestring¦nullName of the employer
addressAddressAddress of the employer

Employee

Properties

NameTypeDescription
namestringName of the employee
addressAddressAddress of the employee
marital_statusstring¦nullTax filing status if printed on the pay stub
taxpayer_idTaxpayerIdA unique identification number of the tax payer

Enumerated Values

PropertyValue
marital_statusMarried
marital_statusSingle
marital_statusNot listed

EmploymentDetails

Properties

NameTypeDescription
hire_datestring(date)¦nullDate of hiring
annual_salarynumerical¦nullAnnual salary
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)¦nullThe date on which a specific pay period begins
pay_period_end_datestring(date)¦nullThe date on which a specific pay period ends
pay_datestring(date)¦nullDate of payment
paystub_providerstring¦nullName of the pay stub provider
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 printed on the pay stub

Enumerated Values

PropertyValue
pay_frequencyMonthly
pay_frequencyBiweekly
pay_frequencyWeekly
pay_frequencySemi-monthly
pay_frequency_capturedWeekly
pay_frequency_capturedBiweekly
pay_frequency_capturedSemi-monthly
pay_frequency_capturedMonthly
pay_frequency_capturedNot listed

NetPay

Properties

NameTypeDescription
distribution_details[PayDistribution]Net pay distribution details
totalsTotalTotal pay

PayDistribution

Properties

NameTypeDescription
descriptionstring¦nullPay distribution description
bank_namestring¦nullName of the bank where payment is received
account_numberstring¦nullAccount number in which payment is received
bank_account_typestring¦nullType of bank account in which payment is received
current_paynumerical¦nullCurrent pay amount

Earnings

Properties

NameTypeDescription
sub_totals[EarningsSubtotal]Sub total earning
totals[EarningsTotal]Total earning

Deductions

Properties

NameTypeDescription
sub_totals[Total]Sub total deductions
totals[Total]Total deductions

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¦nullCurrent pay amount
ytd_paynumerical¦nullPayment amount of the year-to-date

EarningsTotal

Properties

allOf

NameTypeDescription
*anonymous*TotalAnonymous

and

NameTypeDescription
*anonymous*objectAnonymous
» current_hoursnumberCurrent hours

EarningsSubtotal

Properties

allOf

NameTypeDescription
*anonymous*EarningsTotalAnonymous

and

NameTypeDescription
*anonymous*objectAnonymous
» current_ratenumberCurrent rate

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¦nullThe last 4 digits of the 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

Status

Properties

NameDescription
statusStatus of the pay stub processing. The available options are COMPLETED and REJECTED. The below example will help you understand one of the rejection scenarios:

Example: Consider that you uploaded multiple pages of PDF in which a few pages are marked as non-paystub pages. In such case, the status will return as REJECTED.

In the rejected pay stub, all the values are set to null. However, the document still retains its page indexes to indicate the position of each page in the PDF.
rejection_reasonThe reason why the pay stub was rejected.

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
DENTALEmployer-sponsored dental contributions
HEALTH SAVINGS ACCOUNT/HSA/FSAEmployer HSA/FSA contributions
HOLIDAY PAYHoliday earnings
INVESTMENTSEmployer contributions to stock or retirement investments
JURY DUTYJury duty earnings
LIFE INSURANCEEmployer-sponsored life insurance contributions
LEAVELeave earnings that don't fit one of these other descriptions
LOANStudent loan repayment
LONG TERM DISABILITY PAYMENTLong-term disability earnings
MEDICALEmployer-sponsored medical contributions
MILITARY PAYBAS, BAH, BAF
OTHERItems that do not fit other categories
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
RSURestricted stock unit earnings
SEVERANCE PAYCompensation for termination of employment
SHIFT DIFFERENTIALAdditional earnings for working outside normal business hours
SHORT TERM DISABILITY PAYMENTShort-term disability earnings
SICK PAYSick pay earnings
SIGNING BONUSSign-on award compensation
TIPS INCOMETips earnings
VACATIONVacation earnings
VISIONEmployer-sponsored vision plan contributions

Deductions

Deductions from the pay stub

ValueDescription
401KBoth pre-tax and post-tax deductions for defined-contribution retirement plans: 401(k), 403(b), and 457(b)
ALIMONY & CHILD SUPPORTGarnishments to pay Alimony (to a former spouse) or Child Support (from a non-custodial parent)
CAFETERIA/CAFERepayment for meals purchased from the company's cafeteria or cafe. Not to be confused with Section 125 Cafeteria plan deductions such as for Medical and Dental insurance, FSAs, HSAs, etc.
CITY/COUNTY TAXAny city or county tax withholdings
DENTALDental insurance deductions. If Medical and Dental are combined, call it Medical; if Dental and Vision are combined, call it Dental.
DEPENDENT CAREFSA to spend on daycare or other childcare. They separate from Health Savings Account/HSA/FSA.
DISABILITY & FAMILY LEAVE TAXTaxes that fund State Disability Insurance (SDI) and Paid Family (Medical) Leave (Insurance) programs, e.g. SDI, FML, PFL, PFML, FLI, etc.
DONATIONSCharitable and political donations (do not include membership dues or fees)
DUESMiscellaneous dues deducted from gross pay (e.g. Union Dues)
FEDERAL WITHHOLDINGSFederal income tax withholdings, but not Social Security or Medicare (or FICA)
FICACombined Social Security and Medicare tax withholdings
GARNISHMENTSAny wage garnishments besides Child Support or Alimony
HEALTH SAVINGS ACCOUNT/HSA/FSAHealth savings account and flexible spending account contributions except for Dependent Care. Also, section 125 Cafeteria plan deductions and AFLAC don't specify that they are for Medical, Dental, etc.
INVESTMENTSA broad category for retirement plans and other investments besides those included in 401k, including IRA, Pension, and STRS
LEGAL & IDENTITY PROTECTIONLegal and/or identity theft protection services
LIFE INSURANCELife Insurance including Accidental Death and Dismemberment insurance (AD&D), Accident / Injury insurance, and Critical Illness insurance
LOANAny loan payment deducted from employee's earnings, including 401(k) loan and Advance
LONG TERM DISABILITYLong-term disability insurance deductions
MEDICALMedical insurance and hospital. The AD&D and Critical Illness coverage fall under Life Insurance. If Medical and Dental are combined, call it Medical
MEDICARE TAXMedicare tax withholdings. If Social Security and Medicare are combined, that goes to FICA
OFFSETSDeductions to cancel out an amount from the Earnings section, because the amount is not being paid as part of the paycheck. For example, if the amount is being paid into the employee's stock account, or paid as a gift card
OTHERItems that do not fit other categories
SHORT TERM DISABILITYShort-term disability insurance deductions
SOCIAL SECURITY TAXSocial Security tax withholdings, including OASDI (not to be confused with SDI). If Social Security and Medicare are combined, that goes to FICA
STATE TAXState tax withholdings, including for Unemployment Insurance. The SDI and all flavors of PFL fall under the Disability & Family Leave Tax
UNIFORMSDeductions used to pay for workers' uniforms, shoes, boots, safety equipment, and similar
VISIONVision insurance deductions. If Dental and Vision are combined, call it Dental.

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
}