Paystub Standard Extraction

Ocrolus' Paystub Standard Extraction gives you the information you need to verify a borrower's income.

Paystubs can be uploaded as both PDFs and images. Both upload endpoints require the form_type parameter with value PAYSTUB_01.

Usage Guide

To upload a paystub to Ocrolus, follow the below pattern:

  • Create a new book to hold one or more paystubs and other related forms.
  • Upload a PDF or image of the paystub with the form_type parameter set to PAYSTUB_01. Repeat as necessary with additional paystubs or other form types.
  • Retrieve the paystub JSON results by using the Doc Form Data endpoint, or retrieve all forms from the book by using the Book Form Data endpoint.
  • You may check the status of the documents within a book with the Book Status endpoint, but we recommend registering for webhook notifications, which let you know exactly when a document has completed processing.

Standard Fields Captured

JSON AttributeData Type*Description
paystub-Part1-General:employeeNameTextName of the employee that is the subject of the paystub.
paystub-Part1-General:employeeAddress:addressLine1TextAddress Line 1 of the employee.
paystub-Part1-General:employeeAddress:addressLine2TextAddress Line 2 of the employee.
paystub-Part1-General:employeeAddress:cityTextCity of the employee.
paystub-Part1-General:employeeAddress:stateTextState the employee resides in. Formatted as a 2 character state code.
paystub-Part1-General:employeeAddress:zipText5 digit zip code in which employee resides.
paystub-Part1-General:nameOfEmployer/CompanyTextName of the employer issuing the paystub.
paystub-Part2-Dates:payPeriod(BeginningDate)DateThe beginning date of the pay period covered by the paystub.
paystub-Part2-Dates:payPeriod(EndingDate)DateThe ending date of the pay period covered by the paystub.
paystub-Part2-Dates:payDateDateThe date payment was issued.
paystub-Part3-Earnings:grossPay(Current)MoneyThe total pay issued by the employer to the employee for the current pay period covered by the paystub.
paystub-Part3-Earnings:grossPay(Ytd)MoneyThe total pay issued by the employer to the employee from the beginning of the year, including the current pay period.
paystub-Part3-Earnings:netPay(Current)MoneyThe total amount received by the employee for the current pay period covered by the paystub.
paystub-Part3-Earnings:netPay(Ytd)MoneyThe total amount received by the employee from the beginning of the year, including the current pay period.

*In the event the data detected on a page fails validation, the data type changes to "String" and a validation_error message will be included as an optional JSON element on the field.

Validation Responses Error Handling

The following validation response error messages are returned as an validation_error attribute in the corresponding JSON result if any of the validation rules are not met.

Validation RuleValidation Response
paystub-Part2-Dates:payPeriod(BeginningDate) < paystub-Part2-Dates:payPeriod(EndingDate)Beginning Date should be earlier than Ending Date. User should verify document.
paystub-Part2-Dates:payPeriod(EndingDate) > paystub-Part2-Dates:payPeriod(BeginningDate)Ending Date should be later than Beginning Date. User should verify document.
paystub-Part2-Dates:payDate > paystub-Part2-Dates:payPeriod(BeginningDate)Pay Date should be later than Beginning Date. User should verify document.
paystub-Part3-Earnings:grossPay(Current) <= paystub-Part3-Earnings:grossPay(Ytd)Gross Pay (Current) should be less than or equal to Gross Pay (YTD). User should verify document.
paystub-Part3-Earnings:grossPay(Ytd) >= paystub-Part3-Earnings:grossPay(Current)Gross Pay (YTD) should be more than or equal to Gross Pay (Current). User should verify document.
paystub-Part3-Earnings:netPay(Current) < paystub-Part3-Earnings:grossPay(Current)Net Pay (Current) should be less than Gross Pay (Current). User should verify document.
paystub-Part3-Earnings:netPay(Ytd) < paystub-Part3-Earnings:grossPay(Ytd)Net Pay (YTD) should be less than Gross Pay (YTD). Please review.
paystub-Part3-Earnings:netPay(Ytd) >= paystub-Part3-Earnings:netPay(Current)Net Pay (YTD) should be more than or equal to Net Pay (Current). Please review.

Sample Paystub

The below Ocrolus Sample PDF (input) matches the below Sample JSON Result (output).

Sample JSON Result

{
  "form_config_pk": 6634,
  "form_type": "PAYSTUB_01",
  "pk": 5342402,
  "raw_fields": {
    "paystub-Part1-General:employeeAddress:addressLine1": {
      "alias_used": null,
      "is_empty": false,
      "page_doc_pk": 79327626,
      "source_filename": "Ocrolus Sample PDF - Paystub.pdf",
      "value": "121 WILLSWORLD LANE"
    },
    "paystub-Part1-General:employeeAddress:addressLine2": {
      "alias_used": null,
      "is_empty": true,
      "page_doc_pk": 79327626,
      "source_filename": "Ocrolus Sample PDF - Paystub.pdf",
      "value": ""
    },
    "paystub-Part1-General:employeeAddress:city": {
      "alias_used": null,
      "is_empty": false,
      "page_doc_pk": 79327626,
      "source_filename": "Ocrolus Sample PDF - Paystub.pdf",
      "value": "OTHERWORLD"
    },
    "paystub-Part1-General:employeeAddress:state": {
      "alias_used": null,
      "is_empty": false,
      "page_doc_pk": 79327626,
      "source_filename": "Ocrolus Sample PDF - Paystub.pdf",
      "value": "VA"
    },
    "paystub-Part1-General:employeeAddress:zip": {
      "alias_used": null,
      "is_empty": false,
      "page_doc_pk": 79327626,
      "source_filename": "Ocrolus Sample PDF - Paystub.pdf",
      "value": "11234"
    },
    "paystub-Part1-General:employeeName": {
      "alias_used": null,
      "is_empty": false,
      "page_doc_pk": 79327626,
      "source_filename": "Ocrolus Sample PDF - Paystub.pdf",
      "value": "LYRA BELACQUA"
    },
    "paystub-Part1-General:nameOfEmployer/Company": {
      "alias_used": null,
      "is_empty": false,
      "page_doc_pk": 79327626,
      "source_filename": "Ocrolus Sample PDF - Paystub.pdf",
      "value": "COOL PAYSTUB COMPANY"
    },
    "paystub-Part2-Dates:payDate": {
      "alias_used": null,
      "is_empty": false,
      "page_doc_pk": 79327626,
      "source_filename": "Ocrolus Sample PDF - Paystub.pdf",
      "value": "12/18/2018"
    },
    "paystub-Part2-Dates:payPeriod(BeginningDate)": {
      "alias_used": null,
      "is_empty": false,
      "page_doc_pk": 79327626,
      "source_filename": "Ocrolus Sample PDF - Paystub.pdf",
      "value": "12/01/2018"
    },
    "paystub-Part2-Dates:payPeriod(EndingDate)": {
      "alias_used": null,
      "is_empty": false,
      "page_doc_pk": 79327626,
      "source_filename": "Ocrolus Sample PDF - Paystub.pdf",
      "value": "12/15/2018"
    },
    "paystub-Part3-Earnings:grossPay(Current)": {
      "alias_used": null,
      "is_empty": false,
      "page_doc_pk": 79327626,
      "source_filename": "Ocrolus Sample PDF - Paystub.pdf",
      "value": "1917.00"
    },
    "paystub-Part3-Earnings:grossPay(Ytd)": {
      "alias_used": null,
      "is_empty": false,
      "page_doc_pk": 79327626,
      "source_filename": "Ocrolus Sample PDF - Paystub.pdf",
      "value": "64413.39"
    },
    "paystub-Part3-Earnings:netPay(Current)": {
      "alias_used": null,
      "is_empty": false,
      "page_doc_pk": 79327626,
      "source_filename": "Ocrolus Sample PDF - Paystub.pdf",
      "value": "1260.32"
    },
    "paystub-Part3-Earnings:netPay(Ytd)": {
      "alias_used": null,
      "is_empty": true,
      "page_doc_pk": 79327626,
      "source_filename": "Ocrolus Sample PDF - Paystub.pdf",
      "value": ""
    }
  },
  "tables": []
}